Persistent agent identity + memory (Beads/Git)

The accidental Claude Code source-map leak (v2.1.74-2.1.88) gave the industry its first detailed look at a production memory system: Kairos / Dream Mode, a four-stage consolidation pipeline (Orient → Gather → Consolidate → Prune) that maintains agent state across long-horizon tasks spanning ~1,900 files. The architecture validates the Beads/Git pattern - structured, persistent, git-trackable memory - and shows the next move is automated consolidation rather than ad-hoc append-only logs. Expect Kairos-style consolidation to spread to other agents over the next quarter; design your memory layer with consolidation in mind, not just accumulation.

Every AI agent session, by default, starts fresh. The agent has no memory of previous sessions, no accumulated knowledge of your codebase's quirks, no record of decisions made or mistakes learned from. This stateless model is simple and safe, but it creates a ceiling on agent capability: no matter how many sessions an agent completes, it never gets better at your specific codebase.

Persistent agent memory solves this by giving agents a mechanism to record observations, decisions, and learnings between sessions. "Beads" is one such mechanism: a structured memory format where agents write small, discrete memory records ("beads") to files in the repository, organized by topic and date. These files are committed to git alongside the code, giving the agent's memory the same versioning, auditability, and collaborative visibility as the codebase itself.

A Beads memory file might contain entries like: "2025-11-15: Learned that the payment service's retry logic uses exponential backoff with a 2-second base delay - do not suggest reducing this without understanding the downstream rate limit implications." Or: "2025-12-03: The UserRepository.findByEmail method is intentionally non-indexed for compliance reasons - do not suggest adding an index without consulting the privacy team." Or: "2026-01-20: This codebase has a known issue with circular dependency detection in the module loader - avoid mutual imports between service classes."

Over time, a Beads memory accumulates to become something like an agent's institutional memory of the codebase: a record of every non-obvious discovery, every mistake corrected, every hard-won insight that an experienced human developer would keep in their head. The difference is that this knowledge is written down, versioned, shared across agent instances, and accessible to any agent that works on the codebase.

At L5 (Autonomous), agents are expected to maintain their own memory. When an agent makes a discovery or corrects an error, it writes a memory record. When an agent starts a new session, it reads relevant memory records before beginning work. The agent has an identity that persists across sessions and a memory that grows with each task.

Persistent memory fundamentally changes the economics of agent-based development:

• Agents improve with use - each task teaches the agent something about your specific codebase that makes the next task more accurate
• Institutional knowledge scales - the agent's accumulated memory is available to all developers and all agent instances, not locked in any one person's head
• Mistakes don't repeat - a corrected error is written to memory; future sessions don't make the same mistake
• Onboarding accelerates - new agents (and new developers) can read the memory to learn codebase-specific insights that aren't in the code itself
• Context assembly improves - the BYOC pipeline can incorporate relevant memory records in the context package, giving agents access to accumulated wisdom before they start a task

The analogy is the difference between a consultant who starts fresh every engagement and one who maintains detailed notes from every client engagement. The second consultant is dramatically more effective because their prior work compounds.

1. Define your memory schema - Memory records should be structured: date, context (what task was in progress), observation (what was discovered), implication (how this should affect future decisions). Consistent structure makes memory records more reliably useful.
2. Create the memory directory structure - Organize memory records by codebase area or topic: agent-memory/payments/, agent-memory/auth/, agent-memory/infrastructure/. This makes it easy for agents to load only the relevant memory for a given task.
3. Teach the agent to write memory - Add to your CLAUDE.md: "At the end of each session, if you discovered something non-obvious about the codebase, write a memory record to the appropriate agent-memory/ directory. Include the date, what you discovered, and why it matters."
4. Add memory loading to the BYOC pipeline - When assembling context for a task, load the relevant memory records from the appropriate directories. Prioritize recent records and records tagged as high-importance.
5. Establish a memory review process - Memory records are written by agents, but reviewed by humans. Add a periodic review (quarterly or monthly) where the team reads recent memory additions and validates or corrects them. This is how you catch wrong lessons before they compound.
6. Consider memory summarization for long-lived codebases - After months of operation, memory directories may contain hundreds of records. Implement a memory summarization step that produces a compressed summary of the most important lessons from each directory, for inclusion in time-sensitive context windows.

Letting agents write memory without human review. Memory records that are incorrect are more harmful than no memory - they train the agent on false information that then gets applied in future sessions. Every agent-written memory record should go through a lightweight review process before being trusted.

Not providing memory as context. A memory directory full of valuable records is useless if the agent doesn't read it. Ensure your agent configuration loads relevant memory records at session start. The memory is only valuable as context, not as files that exist but aren't read.

Accumulating too much memory without curation. Memory directories that grow without curation produce diminishing returns: the agent is given 50k tokens of historical notes when it needs 5k tokens of the most relevant ones. Implement regular memory curation: consolidate redundant records, remove outdated ones, and surface the most important insights.

Conflating agent memory with ADRs. Architecture Decision Records (ADRs) capture human decisions at the team level. Agent memory records capture agent discoveries at the task level. They're different artifacts serving different purposes. Don't route agent memory records into the ADR process - they'll overwhelm it.