Memory Layers: What the Agent Remembers vs What the Vault Holds
Introduction: Two Kinds of Memory, One System
An agent that remembers everything remembers nothing useful. Raw session logs pile up, context windows overflow, and the important decisions get buried under megabytes of tool output and intermediate reasoning. An agent that remembers nothing useful either — every session starts from zero, every mistake is repeated, every insight is lost the moment the context window closes.
The real problem is not memory vs. no memory. It is which memory, when, and for whom. Hermes solves this with a layered architecture that separates what the agent needs right now from what the system needs forever. The vault holds the durable knowledge. The agent’s memory layers hold the working context. Understanding the boundary between them — and why it exists — is the difference between a system that learns and one that just runs.
The Three Layers Hermes Actually Uses
The Hermes agent ecosystem operates three distinct persistence layers, each with different performance characteristics and different purposes. They are not interchangeable. Treating them as interchangeable is how you end up with a 208MB SQLite database blocking an asyncio event loop for 42 seconds.
Layer 1 — state.db (session memory). SQLite at ~/.hermes/state.db with an FTS5 trigram index. This is the working memory: raw session transcripts, every tool call, every model response, every user message. It accumulates continuously. After pruning, the working copy sits around 208MB with 617 sessions retained. The Dashboard reads it. The Gateway reads it. The CLI reads it. But state.db is not the knowledge layer — it is the transcript layer. You search it when you need to recall what happened in a specific conversation. You do not search it when you need to know what the system knows.
Layer 2 — ChromaDB (semantic memory). A vector database running on port 4002. This is where curated, semantically-searchable memory lives. When an agent profile needs to retrieve knowledge during inference — when it needs to remember what it learned from a previous task, what a wiki page says about a concept, what the last article’s provenance recorded — it reads from ChromaDB. Not from state.db. Not from the Obsidian vault directly. ChromaDB is the memory that matters for reasoning.
Layer 3 — Obsidian vault (human-readable knowledge). The Council Vault at Council-Vault/ is markdown, git-tracked, human-readable. It is the source of truth for the Council’s knowledge graph — entities, concepts, sources, and their interconnections. Agents read and write vault pages via file tools. The vault is not a database. It is a document graph with schema enforcement, link integrity, and provenance. When a wiki page says “this concept is grounded in these sources,” that relationship is stored as a markdown link, not a foreign key.
What the Agent Remembers (Ephemeral)
When a Hermes agent runs a task — drafting an article, debugging a build, publishing a post — it accumulates context. Tool outputs. Intermediate reasoning. Variable values. Decision traces. This context lives in the session transcript (state.db) and in the agent’s context window.
The session transcript is a recording. It is comprehensive and searchable, but it is not structured. You cannot ask state.db “what did the system learn about ChromaDB performance?” without running a full-text search and manually filtering results. You cannot ask it “what is the current article count?” without parsing the MASTER-INDEX-BRIDGE content from a previous session.
This is fine. The session transcript is not supposed to be a knowledge base. It is a log. Its job is to be complete and auditable, not queryable and structured. When you need to know what happened, you search the transcript. When you need to know what the system knows, you look elsewhere.
The ephemeral memory also includes the context window — the 128K or 200K tokens the model sees during a single session. This is the most immediate memory: everything the agent is working on right now. It is the sharpest and the most fragile. When the session ends, the context window is gone. What survives is the session transcript and whatever the agent explicitly wrote to persistent storage.
What the Vault Holds (Durable)
The Council Vault holds knowledge that outlives any individual session. A wiki page about [[hermes-memory-layers]] exists whether or not any agent is currently reading it. A concept page about [[chromadb]] describes the vector database’s role in the system regardless of which session created it. The vault is the institutional memory — the knowledge that persists across sessions, across agents, across model upgrades.
The vault’s power comes from its structure. Every page follows a template. Every claim links to a source. Every concept connects to related concepts. The linting system (S3.3) catches orphans, dead links, and ungrounded quotes mechanically. This is not decoration — it is what makes the vault searchable in ways that raw transcripts are not.
When an agent writes a new article, the article itself becomes a vault node. When a post is published, the MASTER-INDEX-BRIDGE records it. When an idea is approved, the IDEAS-BACKLOG marks it. These are durable facts, not session artifacts. They survive the session that created them.
The Boundary: Why It Matters
The critical architectural insight is that the agent’s ephemeral memory and the vault’s durable knowledge serve different purposes, and confusing them breaks both.
If you treat session transcripts as knowledge, you pollute the retrieval layer with noise. Every failed tool call, every intermediate JSON blob, every “let me try that again” becomes a vector in ChromaDB. Retrieval quality drops. The agent retrieves irrelevant context. Decisions degrade.
If you treat the vault as session memory, you overload it with ephemeral state. The vault becomes a dumping ground for task-specific data that has no long-term value. Pages proliferate without schema. Links break. The graph becomes noise.
The boundary is enforced by design, not by discipline. Session transcripts stay in state.db. Curated knowledge goes to ChromaDB and the vault. The agent reads from ChromaDB during reasoning. The agent reads from the vault during knowledge operations. The agent writes to state.db continuously and to the vault only when something is worth preserving.
The Fourth Layer: Strategic Memory
The four-layer model (documented in hermes-four-memory-layers) adds a strategic layer above the other three. Layers 1-3 handle memory — raw logs, semantic embeddings, and human-readable documents. Layer 4 handles knowledge: the synthesized understanding that emerges when memory is processed, filtered, and connected.
Strategic memory is what the system learns over time, not what any individual session records. It is the difference between having a log of a conversation about ChromaDB performance and knowing, as a system-level fact, that Python GIL plus synchronous sqlite3 blocks asyncio and the permanent fix is aiosqlite. That fact lives in the vault, not in any session transcript.
The publish loop (S3.7) is the mechanism that promotes ephemeral memory into durable knowledge. When an article is drafted from vault material, published to WordPress, and then imported back as a new source node, the loop has converted session-derived insight into institutional knowledge. The vault gets denser. The next article has more material to draw from. The system compounds.
See Also
- [[hermes-memory-layers]] — the three-layer persistence architecture
- [[hermes-four-memory-layers]] — the four-layer model including strategic memory
- [[council-vault]] — the internal knowledge graph
- [[chromadb]] — vector database for semantic retrieval
- [[obsidian-semantic-graph]] — the graph structure of the vault
- [[self-improving-knowledge-base]] — the compound growth thesis
