Agent Memory
Agents have no persistence by default — every session starts with an empty context window. Gemba Flow makes memory the framework’s job, not the agent’s, so what one session learns becomes context the next session inherits without being re-briefed.
Why this matters
Without persistence, every agent session is groundhog day. It re-reads the
same files, re-discovers the same patterns, and makes the same mistakes — at
machine speed. The relearning tax is paid in tokens and time on every session,
and it compounds. A team that’s run twenty /work-ticket sessions has paid
the same opening cost twenty times.
The fix is not “longer context windows.” Even a million-token context window starts empty at session boundary. The fix is to write what matters to durable stores at session end, and read those stores at session start. The agent then operates with the same accumulated knowledge that a long-tenured human teammate would.
The four layers
Memory lives in four places, each optimized for a different read pattern.
| Layer | Lifespan | Read by | Updated by |
|---|---|---|---|
| CLAUDE.md | Persistent, project-wide | Every agent, every session | Manual edits + framework upgrades |
Agent configs (.claude/agents/*.md) | Persistent, role-specific | One agent role at a time | /bootstrap-agents + manual edits |
| Memory MCP entities | Persistent, queryable | Any agent via MCP | /log-session (proposes); /validate-memory (catches missing); /prune-memory (removes stale) |
Session journal (reports/session-journals/) | Per session, appended | Next session’s bootstrap | /log-session |
The four layers cover four read patterns: always-on context (CLAUDE.md), role-specific context (agent configs), queryable structured recall (MCP entities), and cross-session prose narrative (journals). Removing any layer leaves a gap; together they cover the full lifecycle.
Memory entities
The structured layer (MCP) uses four entity naming conventions. The shape matters because agents query by name pattern, not full-text search.
CompletedTicket-{issue-number}— what shipped, where, what changedPattern-{domain}-{short-name}— a reusable pattern found during workLesson-{domain}-{short-name}— a mistake and what we now do insteadDecision-{feature-name}— an architectural choice with rationale
Agents query memory at task start (/work-ticket reads recent CompletedTickets
to learn from how similar tickets shipped). They append at task end
(/log-session proposes new LessonLearned and PatternDiscovered entities for
operator confirmation). The framework hygiene is the read-write loop, not the
entities themselves.
How memory compounds
| Day | What memory carries |
|---|---|
| 1 | CLAUDE.md only — no project history yet |
| 5 | Several CompletedTickets; first Patterns starting to emerge |
| 30 | Recall-able Patterns + Lessons; new agents skip relitigated decisions |
| 90 | Architectural Decisions cross-referenced; new tickets routinely answer “have we tried this before” before starting |
The compounding is the point. The framework does not make any one session smarter; it makes the system smarter over time as memory accumulates and the agents read it.
The anti-pattern
The opposite of structured memory is the long system prompt. A wall of instructions retyped or copy-pasted into every session, drifting silently as the project evolves, with no version history and no shared source of truth between agents.
If you have ever tried to keep three agents in sync by editing a system prompt three times — you have lived this anti-pattern. Gemba Flow replaces it with four named layers that the framework reads and writes on the agents’ behalf.
Where to go next
- If you’re about to run
/log-sessionfor the first time:/log-sessioncovers what gets captured + the structured-reflection step that proposes new MCP entities. - If your Memory MCP feels noisy:
/prune-memoryreviews stale entities with time-decay scoring. - If you want the framework architecture behind memory:
docs/MEMORY-ARCHITECTURE.mdin the repo covers persistence types, data flow, and known gaps.