---
id: ADR-002
title: Project Memory Convention
status: accepted
date: "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

```markdown
---
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.