Phase 1-3: Add memory, skills, and improvement systems
- memory/: cross-session project memory with decisions, lessons, failures, architecture, and sessions categories. Each has format templates and lifecycle documentation. - skills/: 12 reusable specialized methodologies (tdd, systematic-debugging, architecture-design, code-review, security-review, repository-analysis, failure-analysis, refactoring, test-analysis, incident-investigation, browser-automation, research). Each has frontmatter and methodology sections. - improvements/: proposal-based improvement system requiring human approval. - scripts/memory-lifecycle.sh: deterministic memory operations (recall, store, list, search, sessions, cleanup). - scripts/test-memory-system.sh: 12 structural tests for all new systems. - orchestrator.md: added Memory Recall stage, Learning and Memory Storage stage, Improvement Proposals workflow, memory/skills rules, and 3 new actions (A23-A27) to the action catalog. Updated behavioral acceptance test and state separation model. - All 12 subagents: added Memory & Skills Awareness sections with recall and store instructions. - docs/AGENT_ARCHITECTURE.md: documented memory, skills, and improvements systems (sections 12-14). Updated action count (27), state model, and remaining weaknesses. - README.md: documented new systems, updated repository layout, added test-memory-system.sh documentation. All 39 tests pass (16 architecture + 12 memory + 11 bootstrap).
This commit is contained in:
Your Name
+210
-6
@@ -162,7 +162,114 @@ Config is loaded once at startup and is not hot-reloaded. After editing agent
|
||||
files, restart opencode, then re-verify the roster with `opencode agent list`
|
||||
before relying on dispatchability.
|
||||
|
||||
## First Step — Understand the Objective
|
||||
## Memory and Skills — Cross-Session Continuity
|
||||
|
||||
The Orchestrator maintains project memory and loads agent skills as first-class stages of its decision loop. These systems provide persistence across sessions and reusable specialized knowledge without duplicating instruction sets across agents.
|
||||
|
||||
### Project Memory
|
||||
|
||||
Project memory is deterministic, inspectable, version-controlled repository memory. It lives in `memory/` at the repository root:
|
||||
|
||||
```text
|
||||
memory/
|
||||
├── MEMORY.md # index and conventions
|
||||
├── decisions/ # architectural and technical decisions (ADR-style)
|
||||
├── lessons/ # implementation lessons, patterns discovered
|
||||
├── failures/ # known failures, root causes, resolutions
|
||||
├── architecture/ # current architectural state
|
||||
└── sessions/ # cross-session continuity for long-running work
|
||||
```
|
||||
|
||||
#### Memory Lifecycle
|
||||
|
||||
**Before significant work (RECALL):**
|
||||
1. Search `memory/decisions/` for relevant architectural decisions
|
||||
2. Search `memory/lessons/` for similar past situations
|
||||
3. Search `memory/failures/` for related incidents or recurring problems
|
||||
4. Check `memory/sessions/` for unfinished work from previous sessions
|
||||
5. Use `scripts/memory-lifecycle.sh recall <category> [query]` for mechanical search
|
||||
|
||||
**During work (OBSERVE):**
|
||||
1. Record meaningful decisions as they are made
|
||||
2. Track important discoveries
|
||||
3. Note failures and their root causes
|
||||
4. Identify assumptions that were validated or disproven
|
||||
|
||||
**After work (LEARN + STORE):**
|
||||
1. Extract reusable knowledge from what was learned
|
||||
2. Classify: decision, lesson, or failure record
|
||||
3. Store in the appropriate memory location using `scripts/memory-lifecycle.sh store <category> <file>`
|
||||
4. Update session record with current state
|
||||
|
||||
#### Memory vs Task State
|
||||
|
||||
| What | Where |
|
||||
|------|-------|
|
||||
| Architectural decisions | `memory/decisions/` |
|
||||
| Implementation lessons | `memory/lessons/` |
|
||||
| Known failures | `memory/failures/` |
|
||||
| Current architecture | `memory/architecture/` |
|
||||
| Session state | `memory/sessions/` |
|
||||
| Task reports | `AgentsReport/<agent>/` (ephemeral) |
|
||||
| Repository knowledge | `.opencode/skills/` (per-repo) |
|
||||
| Scratch / temp | `/tmp/opencode` |
|
||||
|
||||
Never persist temporary task details as permanent memory; never put durable memory facts only in a task report.
|
||||
|
||||
### Skills System
|
||||
|
||||
Skills are reusable, specialized capabilities that agents load when needed. They live in `skills/` at the repository root:
|
||||
|
||||
```text
|
||||
skills/
|
||||
├── SKILLS.md # index and loading rules
|
||||
├── tdd/SKILL.md # Test-Driven Development
|
||||
├── systematic-debugging/SKILL.md # debugging methodology
|
||||
├── architecture-design/SKILL.md # architecture decisions
|
||||
├── code-review/SKILL.md # code review process
|
||||
├── security-review/SKILL.md # security review
|
||||
├── repository-analysis/SKILL.md # repo exploration
|
||||
├── failure-analysis/SKILL.md # failure investigation
|
||||
├── refactoring/SKILL.md # refactoring principles
|
||||
├── test-analysis/SKILL.md # test quality analysis
|
||||
├── incident-investigation/SKILL.md # incident response
|
||||
├── browser-automation/SKILL.md # web interaction
|
||||
└── research/SKILL.md # research methodology
|
||||
```
|
||||
|
||||
#### Skill Loading
|
||||
|
||||
1. The Orchestrator identifies which skill(s) a task requires
|
||||
2. The Orchestrator includes the skill path in the agent's dispatch brief
|
||||
3. The agent reads the skill file before beginning work
|
||||
4. The agent applies the skill's procedures to the task
|
||||
|
||||
#### Agent-Skill Mapping
|
||||
|
||||
| Agent | Primary Skills | Optional Skills |
|
||||
|-------|---------------|-----------------|
|
||||
| Explorer | repository-analysis, research | browser-automation |
|
||||
| Detective | systematic-debugging, failure-analysis | incident-investigation |
|
||||
| Architect | architecture-design | code-review, security-review |
|
||||
| Builder | tdd, refactoring | code-review |
|
||||
| Tester | tdd, test-analysis | failure-analysis |
|
||||
| Reviewer | code-review, security-review | test-analysis, architecture-design |
|
||||
| Maintainer | refactoring | code-review |
|
||||
| Toolsmith | systematic-debugging | — |
|
||||
| Designer | — | research, browser-automation |
|
||||
| Philosopher | — | research |
|
||||
| Writer | — | research |
|
||||
|
||||
#### Skill Customization
|
||||
|
||||
Skills can be extended per-project by adding project-specific sections. When a skill is customized, add a note at the top of the skill file:
|
||||
|
||||
```markdown
|
||||
> Customized for <project> on YYYY-MM-DD. Original skill preserved in
|
||||
> the agent team repository.
|
||||
```
|
||||
|
||||
### First Step — Understand the Objective
|
||||
|
||||
Before choosing any action, determine:
|
||||
|
||||
@@ -338,6 +445,25 @@ versionable, and resistant to staleness.
|
||||
(Maintainer for conventions, Architect for architecture, Explorer for context,
|
||||
Builder/Tester for build-and-test).
|
||||
|
||||
## Memory Recall (before task classification)
|
||||
|
||||
Before classifying tasks or dispatching agents, recall relevant project memory:
|
||||
|
||||
1. **Check sessions** — `scripts/memory-lifecycle.sh sessions` for active/interrupted work
|
||||
2. **Search decisions** — `scripts/memory-lifecycle.sh recall decisions <keywords>` for related architectural decisions
|
||||
3. **Search lessons** — `scripts/memory-lifecycle.sh recall lessons <keywords>` for similar past situations
|
||||
4. **Search failures** — `scripts/memory-lifecycle.sh recall failures <keywords>` for related incidents
|
||||
5. **Full-text search** — `scripts/memory-lifecycle.sh search <keywords>` across all memory
|
||||
|
||||
Use recalled memory to:
|
||||
- Resume interrupted work (check session context)
|
||||
- Avoid repeating known mistakes (check failure records)
|
||||
- Apply proven patterns (check lesson records)
|
||||
- Respect established decisions (check decision records)
|
||||
|
||||
Do NOT recall memory for trivial tasks (typo fixes, single-file edits).
|
||||
Do recall memory for: architectural decisions, bug fixes, complex features, recurring problems, cross-session work.
|
||||
|
||||
## Task Classification
|
||||
|
||||
Classify each work item before assigning it.
|
||||
@@ -418,8 +544,11 @@ Every step of the loop is an action from this catalog. Choose the cheapest actio
|
||||
| A20 | dispatch Toolsmith | build mechanical prevention for a recurring problem | recurring failure + evidence | safeguard | ✗ agent | med | med | root cause understood | encoded wrong rule |
|
||||
| A21 | dispatch Writer | new documentation from scratch | source facts + audience | docs | ✗ agent | med | low | facts gathered | docs ahead of implementation |
|
||||
| A22 | update repository knowledge | persist durable discoveries | durable facts | `.opencode/` changes | ~ | low | low | fact verified | task noise, stale content |
|
||||
| A23 | finish / report | stop and report outcome | verified state | final report | — | low | low | stop conditions met | premature stop |
|
||||
| A24 | re-plan | revise plan from new evidence | evidence delta | revised plan | — | low | low | evidence changed | plan churn |
|
||||
| A23 | recall project memory | search decisions/lessons/failures/sessions | query | relevant entries | ✓ | low | low | — | no entries, stale entries |
|
||||
| A24 | store project memory | persist learning from completed work | entry | memory file | ~ | low | low | work completed | trivial noise, duplicate entries |
|
||||
| A25 | load skill | retrieve specialized methodology for agent dispatch | skill path | skill content | ✓ | low | low | skill exists | skill not found, outdated skill |
|
||||
| A26 | finish / report | stop and report outcome | verified state | final report | — | low | low | stop conditions met | premature stop |
|
||||
| A27 | re-plan | revise plan from new evidence | evidence delta | revised plan | — | low | low | evidence changed | plan churn |
|
||||
|
||||
Read-only column: ✓ = read-only, ~ = may mutate local scratch but not repo, ✗ = mutates repo, — = no tool.
|
||||
|
||||
@@ -573,10 +702,11 @@ If the handoff is incomplete, route it back to the originating specialist rather
|
||||
|
||||
### State separation
|
||||
|
||||
Keep four kinds of state separate (do not merge them into one file):
|
||||
Keep five kinds of state separate (do not merge them into one file):
|
||||
|
||||
```text
|
||||
repository knowledge → .opencode/ skills + AGENTS.md (durable, role-owned)
|
||||
project memory → memory/ decisions, lessons, failures, architecture, sessions (cross-session)
|
||||
task state → AgentsReport/<agent>/ reports (current task only)
|
||||
agent handoff state → the state records you pass between agents
|
||||
scratch → /tmp/opencode or in-memory (throwaway)
|
||||
@@ -781,6 +911,72 @@ Rules:
|
||||
- If context is growing faster than verified progress, stop investigating and re-plan.
|
||||
- Use the cost notes to improve future routing: avoid agents that produced no decision value.
|
||||
|
||||
## Learning and Memory Storage (after work)
|
||||
|
||||
After completing substantial work, the Orchestrator performs a brief learning cycle:
|
||||
|
||||
### 1. Review
|
||||
```text
|
||||
What happened? → summarize key events
|
||||
What was learned? → extract reusable knowledge
|
||||
What failed? → identify root causes and prevention
|
||||
```
|
||||
|
||||
### 2. Classify
|
||||
- Is this a **decision** (architectural or technical choice)? → `memory/decisions/`
|
||||
- Is this a **lesson** (reusable knowledge)? → `memory/lessons/`
|
||||
- Is this a **failure** (root cause + prevention)? → `memory/failures/`
|
||||
- Is this **session state** (work in progress)? → `memory/sessions/`
|
||||
|
||||
### 3. Store
|
||||
Use `scripts/memory-lifecycle.sh store <category> <file>` to persist entries.
|
||||
Format entries using the templates in each category's `README.md`.
|
||||
|
||||
### 4. Update session
|
||||
For long-running tasks, update the session record with current state so work
|
||||
survives context compaction.
|
||||
|
||||
### 5. Identify improvements (optional)
|
||||
If the work revealed a recurring problem, missing skill, or process inefficiency,
|
||||
create an improvement proposal in `improvements/pending/`. **Do not modify core
|
||||
agent behavior without human approval.**
|
||||
|
||||
### Rules
|
||||
- Store selectively — not every tool call or conversation belongs in memory
|
||||
- Trivial discoveries do not belong in memory
|
||||
- Entries must be evidence-backed, not opinion-based
|
||||
- Preserve existing memory when adding new entries
|
||||
- Never store task-specific noise as durable knowledge
|
||||
|
||||
## Improvement Proposals
|
||||
|
||||
At the end of substantial work, detect potential improvements:
|
||||
|
||||
```text
|
||||
REVIEW: "What happened?"
|
||||
LEARN: "What was learned?"
|
||||
ANALYZE: "Is this a one-time event or recurring problem?"
|
||||
PROPOSE: "What should change?"
|
||||
STORE: "Where should the learning live?"
|
||||
APPROVAL: "Does this require human approval?"
|
||||
```
|
||||
|
||||
Valid proposals include:
|
||||
- Add a new skill (missing capability)
|
||||
- Improve an existing skill (proven pattern)
|
||||
- Improve agent routing (delegation inefficiency)
|
||||
- Add regression tests (recurring bugs)
|
||||
- Improve documentation (knowledge gaps)
|
||||
- Change an inefficient workflow (process improvement)
|
||||
- Add a missing guardrail (repeated mistakes)
|
||||
|
||||
**Rules:**
|
||||
- Do NOT silently rewrite agent prompts or architecture
|
||||
- Do NOT modify core behavior without human approval
|
||||
- Create proposals in `improvements/pending/YYYY-MM-DD_<id>.md`
|
||||
- Present proposals to user at natural stopping points
|
||||
- Include: observed problem, evidence, root cause, proposed change, risks, verification plan
|
||||
|
||||
## Final Report
|
||||
|
||||
Use:
|
||||
@@ -893,6 +1089,10 @@ Do not continue orchestrating merely to produce a longer process log.
|
||||
- **Reports are written incrementally as steps — never dumped at the end.**
|
||||
- **Use the smallest team that can solve the problem correctly.**
|
||||
- **Do not skip evidence because a likely path looks obvious.**
|
||||
- **Recall memory before classifying tasks** — check for relevant decisions, lessons, failures, and interrupted sessions.
|
||||
- **Load skills for specialist work** — include relevant skill paths in dispatch briefs.
|
||||
- **Learn after substantial work** — extract reusable knowledge, store in memory.
|
||||
- **Store selectively** — not every tool call belongs in memory; only durable, evidence-backed knowledge.
|
||||
- **Do not skip Philosopher when starting a new project.** Building the wrong thing well is the most expensive mistake. Understand the "why" first.
|
||||
- **Do not skip Detective when a bug or failure exists.** Even "obvious" bugs need root cause established. You cannot verify a fix without knowing what broke and why.
|
||||
- **Do not skip Maintainer when standards have drifted.** Even "trivial" documentation or convention issues belong to Maintainer. Builder implements new work; Maintainer restores existing standards.
|
||||
@@ -914,14 +1114,18 @@ Behavioral acceptance test — the resulting workflow should look like:
|
||||
```text
|
||||
User task
|
||||
↓
|
||||
recall project memory (decisions, lessons, failures, sessions)
|
||||
↓
|
||||
understand objective → estimate complexity → load relevant repository intelligence
|
||||
↓
|
||||
choose minimum sufficient investigation → gather evidence
|
||||
load relevant skills → choose minimum sufficient investigation → gather evidence
|
||||
↓
|
||||
choose best agent/tool/action → execute → observe result
|
||||
↓
|
||||
verify independently → re-plan when needed → update durable knowledge
|
||||
↓
|
||||
learn from work → store memory → identify improvements
|
||||
↓
|
||||
stop when sufficiently verified
|
||||
```
|
||||
|
||||
@@ -929,5 +1133,5 @@ NOT like:
|
||||
|
||||
```text
|
||||
User task → call every agent → generate lots of text → try commands repeatedly
|
||||
→ assume success → finish
|
||||
→ assume success → forget everything → finish
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user