Memory Map: unified registry and coordination layer for Hermes Agent memory systems.
God's to God, Caesar's to Caesar.
Memory Map is a registry and coordination layer — it does not store memory content. It records where memory lives and how to find it. The memory storage systems (Memory Routing for system-prompt-layer hot memory, memOS for semantic-layer cold memory, and any future system) remain independent and unchanged.
Memory Map is the library's catalog, not the books themselves.
Hermes Agent now has (and will continue to have) multiple memory subsystems, each with its own storage, retrieval path, and lifecycle:
| Layer | System | Storage | Access Pattern |
|---|---|---|---|
| Hot (system prompt) | Memory Routing | Local Markdown files | Always injected, read on-demand via read_file |
| Cold (semantic search) | memOS | Neo4j + Qdrant + Redis | On-demand via MCP tools (memos_search, memos_add) |
| Future | ? | ? | ? |
Current gap: These systems are independent and unaware of each other. The agent must decide — for every memory query — whether to read_file a sub-document or call memos_search. This cognitive overhead leads to:
- Missed recall — the agent checks one layer but not the other, missing relevant memories
- Duplication — the same fact stored in both layers with no consistency check
- No lifecycle management — hot memory stays hot forever; cold memory never rises to hot
- No unified view — the agent cannot easily answer "where do I have information about X?"
Memory Map is a lightweight registry that sits above all memory subsystems and provides:
┌─────────────────────────────────────────────┐
│ Memory Map (Registry) │
│ │
│ Hot Layer (system prompt, always-on) │
│ ├── infrastructure → memory/infra.md │
│ ├── philosophy → memory/phil.md │
│ ├── milestones → memory/milestones.md │
│ ├── rules → memory/rules.md │
│ ├── commitments → memory/commitments.md │
│ └── dev-log → memory/dev-log.md │
│ │
│ Cold Layer (semantic search, on-demand) │
│ ├── text_mem → memOS / Qdrant │
│ ├── pref_mem → memOS / Qdrant │
│ ├── tool_mem → memOS / Qdrant │
│ └── skill_mem → memOS / Qdrant │
│ │
│ Registry itself → memory/memory-map.md │
└─────────────────────────────────────────────┘
Memory Map does three things:
A single document (memory/memory-map.md) that lists every memory subsystem, its content scope, storage location, and access method. Injected into the system prompt so the agent always knows its full memory landscape.
As future capabilities are built, Memory Map provides hooks for:
- Cross-system queries — search hot + cold layers simultaneously
- Collaborative writes — when a memory is written to one layer, optionally register it in another
- Lifecycle management — hot ↔ cold memory migration based on access patterns
Detects conflicts between layers (e.g., hot memory says "vLLM at IP A" but cold memory says "vLLM at IP B") and flags them for review.
- Memory Map ≠ Memory Storage. It records where memory lives, never what memory contains.
- Each subsystem owns its data. Memory Routing writes to Markdown files. memOS writes to Qdrant. Memory Map writes to the registry. No subsystem reads or modifies another's storage.
- Opt-in coordination. Cross-system features are additive — existing subsystems work identically without Memory Map.
- The registry is small. The
memory-map.mdfile stays compact enough to be injected into the system prompt (~1000 chars target).
Concept only. This document captures the architectural intent. Engineering design and implementation will follow as our understanding deepens and production needs evolve.
| Phase | Goal | Status |
|---|---|---|
| Phase 0 | Concept document (this repo) | ✅ Done |
| Phase 1 | Static registry (memory-map.md) |
Planned |
| Phase 2 | Unified query tool (memory_map_query) |
Planned |
| Phase 3 | Collaborative write hooks | Planned |
| Phase 4 | Lifecycle management (hot ↔ cold) | Planned |
Memory Routing (repo) is the hot memory subsystem — it handles keyword-based routing of MEMORY.md content into topic-specific sub-documents. It is a peer subsystem, not a parent or child of Memory Map.
Memory Map will eventually know about Memory Routing's sub-documents (list them in the registry), but will never modify how Memory Routing works.
Built through human-AI collaboration:
| Role | Contribution |
|---|---|
| Project Lead | Architectural vision, scope definition |
| AI Agent | Concept documentation, analysis |
MIT