Bernd Worsch
4b4b1ff1f1
- Add docs/adr/ADR-001-workplan-convention.md (formalises existing convention) - Add docs/adr/ADR-002-project-memory-convention.md (file location, structure, session protocols, opt-out, CLI interface) - Implement `kaizen-agentic memory` command group: show, init, brief, clear - Memory stored at .kaizen/agents/<name>/memory.md in project root - `init` scaffolds the standard memory template with YAML frontmatter - `brief` lists all agent memories + note that coach synthesis is pending T13 - `clear` deletes with confirmation prompt WP-0002 T07 and T08 done. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
---
|
|
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.
|