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:
57
docs/adr/ADR-001-workplan-convention.md
Normal file
57
docs/adr/ADR-001-workplan-convention.md
Normal 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.
|
||||
119
docs/adr/ADR-002-project-memory-convention.md
Normal file
119
docs/adr/ADR-002-project-memory-convention.md
Normal 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.
|
||||
Reference in New Issue
Block a user