## Definition A **layered memory architecture** is the practice of stacking three complementary persistence layers — source-of-truth files, harness-managed memory, structured external stores — each with a different write discipline and retrieval pattern. ## The Three Layers ### Layer 1 — Source-of-truth files (in the repo) Slowest-changing, most durable. Reviewed in PRs, survives team turnover. ``` docs/ ├── ARCHITECTURE.md ├── DECISIONS.md # ADRs — see [[Architecture Decision Record]] ├── CONVENTIONS.md └── GLOSSARY.md ``` Write when a decision is **final** and **load-bearing for future agents**. ### Layer 2 — Harness-managed memory The auto-managed file store the agent writes between turns. In Claude Code: `~/.claude/projects/<project>/memory/`. Captures user preferences, feedback, evolving project facts, references to external systems. See [[Auto-memory]]. ### Layer 3 — Structured external stores (e.g., Engram) For large projects: records entities (specs, decisions, incidents, people) and the relationships between them, queryable via MCP. Provides cross-reference, decay management, and shared visibility across multi-agent setups. ## Memory Scopes | Scope | Where it lives | Decay rate | Example | | --------- | ----------------------------------------- | ---------- | -------------------------------- | | User | `~/.claude/memory/` | Slow | "Prefers terse responses." | | Project | `~/.claude/projects/<id>/memory/` or `docs/` | Medium | "We use RLS for tenant isolation." | | Session | Conversation history | Fast | "Let's call this var `tenantId`." | ## Failure Modes - *Promoting session facts to project too eagerly.* Wait for stability. - *Letting project facts pollute user memory.* "User prefers Postgres" is a project fact, not a preference. ## Related - [[Context vs Memory]] - [[Architecture Decision Record]] - [[Auto-memory]] - [[Hierarchical Retrieval]]