Hermes Wiki
AgentStack/Agents/memory-architecture

Memory Architecture — Spec (Draft)

Status: draft. Maps the memory setups already running or spec'd across this "vault + hermes + Claude Code" stack onto the taxonomy in LLM_Memory. Nothing here is new infrastructure — it's naming what already exists and deciding how the pieces should (or shouldn't) talk to each other. Written via the "Update memory architecture" trigger in AgentStack/system_prompt.

1. Why This Exists

Four distinct memory systems are either running or fully spec'd for this stack, and none of them currently reference each other:

  1. Claude Code's own cross-session harness memory (this assistant, this project)
  2. Hermes's Logs/memory/ pipeline (nightly agent run history — spec'd in hermes-harness-spec §3, not yet implemented)
  3. The vault's own content layers (TechResearch/, wiki/, opportunities/, Tools/) — functioning as long-term memory without ever being named as such
  4. Tools/LLM_Memory.md — the taxonomy meant to unify all of the above, currently a thin Notion-imported stub with no mapping to any of them

Without a map, each system risks duplicating what another already stores — worst case, Claude Code's harness memory re-learning vault conventions that are already written down in README.md, and drifting from them over time instead of just re-reading the source of truth.

2. The Taxonomy

From LLM_Memory — not redefined here, just referenced:

  • Short-term (in-context) — current session only, never persisted
  • Long-term:
    • Semantic — facts and knowledge
    • Episodic — past interactions/events
    • Procedural — how-to knowledge

3. The Four Setups, Mapped

Setup Storage Taxonomy category Writer Reader Retention
1. Claude Code harness memory ~/.claude/projects/-home-mihir-pkm/memory/*.md Semantic (user/project/reference types) + procedural (feedback type) Claude Code, interactively, during any session Claude Code, auto-loaded at session start Manual — no expiry; edited or removed as facts change
2. Hermes Logs/memory/ pipeline Logs/memory/YYYY-MM-DD.md (live, 2026-07-02) → YYYY-MM.md → YYYY.md (both not yet implemented) Episodic (daily/monthly) → semantic (yearly milestones) Hermes nightly agents — AgentStack/Hermes/dispatcher.py (DISPATCHER + LINT-AGENT, Python) and lint.md/synthesis.md (SYNTHESIS-AGENT, via claude --print), gated by AgentStack/Hermes/validator.py WIKI-CONSOLIDATION-AGENT (not yet built), morning review 15 daily / 3 monthly / forever yearly — per hermes-harness-spec §3.1
3. Vault content layers TechResearch/, wiki/, opportunities/, Tools/ Semantic (TechResearch, wiki, Tools) + episodic (opportunities, dated) Claude Code, on trigger, per each folder's system_prompt.md Claude Code + Mihir, read on demand TechResearch/: forever, read-only once written. wiki/: forever. opportunities/: until actioned or discarded.
4. Logs/YYYY.md raw event log Logs/YYYY.md Episodic, unbounded LINT-AGENT + future agents Logs/memory pipeline (as source), Mihir (audit) Forever, append-only

4. Overlap and Boundaries — What Should NOT Duplicate What

  • Setup 1 (Claude Code harness memory) must not re-derive vault conventions already written in README.md or any folder's system_prompt.md — those are read fresh every session per the vault's own rules, not memorized. What is legitimately harness-memory material: Mihir's standing preferences about how Claude Code should behave in this vault (procedural/feedback type), and in-flight priorities or decisions made in conversation that haven't yet been written into a vault file (project type).
  • Setup 2 (Hermes Logs/memory/) is operational history of the pipeline itself — not vault content. It must never become a place where vault knowledge lives permanently; that is setup 3's job. hermes-harness-spec.md §3 already draws this line ("not a replacement for Logs/YYYY.md"); this section extends the same boundary to setup 1.
  • Setup 3 (vault content layers) is the project's actual long-term semantic memory — the "what do we know" layer. Setups 1 and 2 are both "how does the assistant/pipeline operate" layers, one interactive, one automated.
  • Setup 4 (Logs/YYYY.md) is the raw ground truth feeding setup 2's daily tier — already established in hermes-harness-spec.md §3, restated here only so the map is complete.

5. Resolved: Should Harness Memory Point at This Spec?

No. Claude Code's own memory-saving rules explicitly exclude "architecture, file paths, or project structure" from memory, since it's derivable by reading the current project state — and that's exactly what this document is. Saving a memory that says "there's a memory-architecture spec at AgentStack/Agents/memory-architecture.md" would violate that exclusion for no benefit: the README's system-prompt rule (README.md rule 2) already guarantees this folder's system_prompt.md — and by extension its specs — gets read when relevant. This is the boundary from §4 working correctly, not an open question.

6. Open Questions

  1. Hermes's Logs/memory/ pipeline (setup 2) is fully spec'd but not implemented. Does this map need to wait for that build, or does naming the intended shape now still pull its weight ahead of implementation? Leaning toward: pulls its weight now — implementation review would go faster without commit relitigating the taxonomy fit.
  2. wiki/'s promotion rubric (hermes-harness-spec.md §7) is still unconfirmed. This doc inherits that same open item rather than re-litigating it — flagged here so it doesn't get lost across two specs.

7. Decisions (2026-07-02)

Question Decision
Scope of this pass Map existing/spec'd setups only. No new infrastructure, no new memory-tool adoption (mem0, Mempalace deferred — see Tools/mem0, Tools/Mempalace if that path gets chosen later).
Relationship to hermes-harness-spec.md Additive, not a restatement. This spec places hermes-harness-spec.md §3's Logs/memory design in context alongside the other three setups; it does not redesign it.
Harness memory pointing at this spec Resolved no — see §5.
Hermes Wiki