# Memory Model

## Overview

HOM Local stores memories as structured records in SQLite with source attribution, quality scores, and vector embeddings for approximate search.

## Memory structure

```json
{
  "memory_id": "uuid",
  "key": "architecture:boundaries",
  "value": "The brain owns memory, ledger, and diagnostics. Provider implementations are app-layer concerns.",
  "memory_type": "declarative",
  "source": "brain-e2e-test",
  "session_id": "session-1",
  "project_id": "project-alpha",
  "track": "conversation",
  "quality_score": 0.92,
  "created_at_s": 1700000000,
  "updated_at_s": 1700000000,
  "metadata": {
    "kind": "session_compaction_continuity_v1",
    "native_compaction": true,
    "model_agnostic": true
  }
}
```

## Memory types

| Type | Description |
|------|-------------|
| `declarative` | Factual knowledge |
| `procedural` | How-to instructions |
| `episodic` | Event sequences |
| `semantic` | Conceptual relationships |
| `action_trace` | Tool execution traces |
| `reasoning` | Reasoning artifacts |

## Source attribution

Every memory tracks its origin:

- **Direct**: User input or API call
- **Import**: External data import
- **Reasoning**: Generated by reasoning engine
- **Compaction**: Session compaction artifact
- **Nightly**: Nightly maintenance operation

## Quality scoring

Quality scores range from 0.0 to 1.0:

```
quality_score = form_score * filter_score * substance_score * factuality_score
```

### Quality walls

1. **Form**: Structural correctness (0.0-1.0)
2. **Filter**: Relevance and deduplication (0.0-1.0)
3. **Substance**: Evidence strength and citation coverage (0.0-1.0)
4. **Factuality**: Atomic precision (0.0-1.0)

## Vector embeddings

Memories can have vector embeddings for approximate search:

```json
{
  "memory_id": "uuid",
  "embedding_model": "text-embedding-3-small",
  "vector": [0.1, 0.2, ...],
  "dimensions": 1536
}
```

### Search modes

| Mode | Description | When to use |
|------|-------------|-------------|
| `exact` | Full scan cosine similarity | Corpus < 10K |
| `hybrid_candidate_exact_rerank` | PQ candidates + exact rerank | Corpus > 10K |
| `blocked_threshold_missing` | Blocked until threshold profile exists | Any size |

## Recall pipeline

1. **Query parsing**: Extract terms and intent
2. **Mode selection**: Choose recall strategy
3. **Candidate retrieval**: Get initial candidates
4. **Scoring**: Apply quality and relevance scores
5. **Ranking**: Sort by combined score
6. **Packaging**: Assemble evidence cards
7. **Audit**: Attach audit guidance metadata

## Session compaction

When context windows fill up, sessions can be compacted:

1. **Artifact creation**: Save full source memory detail
2. **Compartmentalization**: Split into conversation, tool_usage, action_taken
3. **Summary generation**: Create concise post-compaction summary
4. **Continuity guarantee**: Ensure no information loss

## Import system

### Memory packs

External data is imported via memory packs:

```json
{
  "memories": [
    {
      "key": "imported:memory",
      "value": "Memory content",
      "memory_type": "declarative",
      "source": "external-data"
    }
  ]
}
```

### Import validation

- Deduplication by key
- Quality gate assessment
- Provenance tracking
- Bridge event creation