# Memory Systems

Architectures for persistent context beyond the window.

## Memory Layer Architecture

| Layer              | Scope          | Persistence | Use Case         |
| ------------------ | -------------- | ----------- | ---------------- |
| L1: Working        | Current window | None        | Active reasoning |
| L2: Short-Term     | Session        | Session     | Task continuity  |
| L3: Long-Term      | Cross-session  | Persistent  | User preferences |
| L4: Entity         | Per-entity     | Persistent  | Consistency      |
| L5: Temporal Graph | Time-aware     | Persistent  | Evolving facts   |

## Benchmark Performance (DMR Accuracy)

| System     | Accuracy | Approach                  |
| ---------- | -------- | ------------------------- |
| Zep        | 94.8%    | Temporal knowledge graphs |
| MemGPT     | 93.4%    | Hierarchical memory       |
| GraphRAG   | 75-85%   | Knowledge graphs          |
| Vector RAG | 60-70%   | Embedding similarity      |

## Vector Store with Metadata

```python
class MetadataVectorStore:
    def add(self, text, embedding, metadata):
        doc = {
            "text": text, "embedding": embedding,
            "entities": metadata.get("entities", []),
            "timestamp": metadata.get("timestamp")
        }
        self.index_by_entity(doc)

    def search_by_entity(self, entity, k=5):
        return self.entity_index.get(entity, [])[:k]
```

## Temporal Knowledge Graph

```python
class TemporalKnowledgeGraph:
    def add_fact(self, subject, predicate, obj, valid_from, valid_to=None):
        self.facts.append({
            "triple": (subject, predicate, obj),
            "valid_from": valid_from,
            "valid_to": valid_to or "current"
        })

    def query_at_time(self, subject, predicate, timestamp):
        for fact in self.facts:
            if (fact["triple"][0] == subject and
                fact["valid_from"] <= timestamp <= fact["valid_to"]):
                return fact["triple"][2]
```

## Memory Retrieval Patterns

| Pattern      | Query             | Use Case       |
| ------------ | ----------------- | -------------- |
| Semantic     | "Similar to X"    | General recall |
| Entity-based | "About user John" | Consistency    |
| Temporal     | "Valid on date"   | Evolving facts |
| Hybrid       | Combine above     | Production     |

## File-System-as-Memory

```
memory/
├── sessions/{id}/summary.md
├── entities/{id}.json
└── facts/{timestamp}_{id}.json
```

## Guidelines

1. Start with file-system-as-memory (simplest)
2. Add vector search for scale
3. Use entity indexing for consistency
4. Add temporal awareness for evolving facts
5. Implement consolidation for health
6. Measure retrieval accuracy

## Related

- [Context Fundamentals](./context-fundamentals.md)
- [Multi-Agent Patterns](./multi-agent-patterns.md)