kaizen-agentic/docs/adr/ADR-002-project-memory-convention.md

id, title, status, date

id	title	status	date
ADR-002	Project Memory Convention	accepted	2026-03-18

ADR-002 — Project Memory Convention

Status

Accepted

Context

kaizen-agentic agents are stateless by default — each session starts from scratch with no knowledge of what has been tried, what worked, or what the project's recurring patterns are. This makes agents less useful over time and forces the operator to re-supply context that the agent itself accumulated.

Decision

Each agent deployed into a project may maintain a project-scoped memory file. Memory files are written at session close and read at session start.

File location

<project-root>/.kaizen/agents/<agent-name>/memory.md

The .kaizen/ directory is the kaizen-agentic ecosystem's project-level state directory, analogous to .claude/ for Claude Code.

Memory file structure

---
agent: <agent-name>
project: <project-root or slug>
last_updated: <ISO date>
session_count: <n>
---

## Project Context
<!-- What this agent knows about the project it works in -->

## Accumulated Findings
<!-- Patterns, recurring issues, key decisions encountered -->

## What Worked
<!-- Approaches that produced good results in this project -->

## Watch Points
<!-- Recurring risks, traps, or areas requiring extra care -->

## Open Threads
<!-- Things noticed but not yet acted on -->

## Session Log
<!-- One-line entry per session: date · summary · outcome -->

Session-start protocol (all memory-enabled agents)

1. Check for .kaizen/agents/<name>/memory.md in the project root.
2. If present, read it before beginning work.
3. Acknowledge the memory in the opening brief.

Session-close protocol (all memory-enabled agents)

1. Update ## Accumulated Findings, ## What Worked, ## Watch Points as needed.
2. Append one line to ## Session Log.
3. Bump last_updated and session_count.

Agent opt-out

An agent may declare memory: disabled in its YAML frontmatter to opt out. Default is enabled. Stateless utility agents (e.g. keepaTodofile) should opt out.

CLI interface

kaizen-agentic memory show <agent>   # Print agent memory for current project
kaizen-agentic memory init <agent>   # Scaffold empty memory file
kaizen-agentic memory brief <agent>  # Run coach, print orientation for agent
kaizen-agentic memory clear <agent>  # Wipe memory (with confirmation prompt)

memory init creates the .kaizen/agents/<name>/memory.md file with the standard structure and populates the frontmatter.

Coaching meta-agent

A dedicated agent-coach.md (category: meta) reads across all .kaizen/agents/*/memory.md files in a project and:

• Synthesises a cross-agent brief (shared patterns, cross-domain risks)
• Produces a new-agent orientation targeted at a specific agent about to be deployed for the first time
• Maintains its own memory covering meta-level fleet observations

kaizen-agentic memory brief <agent> invokes the coach to produce this orientation.

Consequences

• Agents accumulate project-specific knowledge and arrive in later sessions informed rather than blank.
• The .kaizen/ directory should be added to .gitignore by default; teams may choose to commit it for shared context.
• Memory files are human-readable and can be manually edited or reviewed.
• The coach agent provides a single synthesised view across all agent memories — reducing the operator's burden of re-supplying context.
• Agents with memory: disabled remain fully stateless and require no .kaizen/ setup.