feat(memory): add memory CLI command group and project memory ADRs

- 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>
This commit is contained in:
2026-03-18 23:25:48 +00:00
parent eff77973a1
commit 4b4b1ff1f1
4 changed files with 312 additions and 2 deletions

View File

@@ -0,0 +1,57 @@
---
id: ADR-001
title: Workplan Convention
status: accepted
date: "2026-03-18"
---
# ADR-001 — Workplan Convention
## Status
Accepted
## Context
kaizen-agentic needs a way to track planned work that is version-controlled,
visible to the state-hub, and authoritative when the two diverge.
## Decision
Work items originate as Markdown files in `workplans/` **before** being
registered in the state-hub DB. The file is always authoritative; the DB is
a read/query model derived from it.
**File naming:** `workplans/kaizen-agentic-WP-NNNN-<slug>.md`
**ID prefix:** `KAIZEN-WP`
### Required YAML frontmatter
```yaml
---
id: KAIZEN-WP-NNNN
type: workplan
title: "..."
domain: custodian
repo: kaizen-agentic
status: active | completed | archived
owner: kaizen-agentic
topic_slug: custodian
state_hub_workstream_id: <uuid>
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
---
```
### Task tracking
Tasks use `- [ ]` / `- [x]` checkboxes with a `T##` code prefix. A
`## State Hub Task IDs` table at the end of each workplan maps codes to
DB UUIDs so status can be synced without a list_tasks lookup.
## Consequences
- File is the source of truth; DB drift is auto-fixable via
`check_repo_consistency(fix=True)`.
- Tasks must be created in the file first, then registered in the hub.
- C-12 warnings are expected when the DB host has not yet seen local changes.

View File

@@ -0,0 +1,119 @@
---
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.