diff --git a/.config/opencode/AGENTS.md b/.config/opencode/AGENTS.md index d869546..434816d 100644 --- a/.config/opencode/AGENTS.md +++ b/.config/opencode/AGENTS.md @@ -1,36 +1,130 @@ -## Project Memory +## Memory System (Dual: Global + Per-Project) -Use markdown files in `.memory/` as the persistent project memory across sessions. This is the source of truth for architecture, decisions, plans, research, and implementation state. +Memory is split into two complementary systems: + +1. **Global Memory (basic-memory)** — cross-project knowledge via MCP server. Stores reusable patterns, conventions, tech knowledge, domain concepts, and lessons learned. Lives in `~/basic-memory/`, accessed via MCP tools. +2. **Project Memory (`.memory/`)** — per-project state committed to git. Stores plans, gates, sessions, project-specific decisions, research, and architecture. Lives in the project's `.memory/` directory. + +### Global Memory (basic-memory) + +[basic-memory](https://github.com/basicmachines-co/basic-memory) is an MCP server that provides persistent knowledge through structured markdown files indexed in SQLite with semantic search. + +**What goes in global memory:** +- Reusable coding patterns (error handling, testing, logging) +- Technology knowledge (how libraries/frameworks/tools work) +- Convention preferences (coding style decisions that span projects) +- Domain concepts that apply across projects +- Cross-project lessons learned and retrospectives +- SME guidance that isn't project-specific + +**MCP tools (available to all agents):** +- `write_note(title, content, folder, tags)` — create/update a knowledge note +- `read_note(identifier)` — read a specific note by title or permalink +- `search_notes(query)` — semantic + full-text search across all notes +- `build_context(url, depth)` — follow knowledge graph relations for deep context +- `recent_activity(type)` — find recently added/updated notes + +**Note format:** +```markdown +--- +title: Go Error Handling Patterns +permalink: go-error-handling-patterns +tags: +- go +- patterns +- error-handling +--- +# Go Error Handling Patterns + +## Observations +- [pattern] Use sentinel errors for expected error conditions #go +- [convention] Wrap errors with fmt.Errorf("context: %w", err) #go + +## Relations +- related_to [[Go Testing Patterns]] +``` + +**Usage rules:** +- At session start, use `search_notes` or `build_context` to find relevant global knowledge before starting work. +- After completing work with reusable lessons, use `write_note` to record them globally. +- Use WikiLinks `[[Topic]]` to create relations between notes. +- Use tags for categorization: `#pattern`, `#convention`, `#sme`, `#lesson`, etc. +- Use observation categories: `[pattern]`, `[convention]`, `[decision]`, `[lesson]`, `[risk]`, `[tool]`. + +### Project Memory (`.memory/`) + +Per-project state, committed to git. This is the source of truth for active project work. **Directory structure:** ```text .memory/ - knowledge.md # Persistent project knowledge (architecture, patterns, key concepts) - decisions.md # Architecture decisions, SME guidance, design choices - plans/ # One file per active plan/feature - .md # Plan with tasks, statuses, acceptance criteria - research/ # Research findings - .md # Research on a specific topic +├── manifest.yaml # Index: all files with descriptions + groups +├── system.md # One-paragraph project overview +│ +├── knowledge/ # Project-specific knowledge +│ ├── overview.md # THIS project's architecture +│ └── tech-stack.md # THIS project's technologies +│ +├── decisions.md # Project-specific Architecture Decision Records +│ +├── plans/ # Active plans (one per feature) +│ └── .md +│ +├── research/ # Project-specific research findings +│ └── .md +│ +├── gates/ # Quality gate records +│ └── .md # Review + test outcomes +│ +└── sessions/ # Session continuity + └── continuity.md # Rolling session notes ``` -**Workflow: read files → work → update files** +**Workflow: global context → project context → work → update both** -1. **Session start:** Read `.memory/` directory contents and skim `.memory/knowledge.md`. -2. **Before each task:** Read relevant `.memory/*.md` files before reading source files for project understanding. -3. **After each task:** Update the appropriate `.memory/*.md` files with what was built. +1. **Session start:** Query basic-memory (`search_notes`) for relevant global context, then read `.memory/manifest.yaml` and relevant project files. +2. **Before each task:** Check global memory for reusable patterns/guidance, then read relevant `.memory/` files for project state. +3. **After each task:** Update `.memory/` for project state. If the work produced reusable knowledge, also `write_note` to basic-memory. +4. **Quality gates:** Record reviewer/tester outcomes in `.memory/gates/.md` (project-specific). -Be specific in summaries: include parameter names, defaults, file locations, and rationale. Keep concepts organized as markdown sections (`## Heading`) and keep hierarchy shallow. +**Manifest schema:** + +```yaml +name: +version: 1 +categories: + - path: + description: + group: +``` **Recording discipline:** Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If an entry would only say "we started phase X", don't add it. Memory files preserve *knowledge*, not *activity logs*. **Read discipline:** -- Read only the `.memory/` files relevant to the current task; avoid broad re-reads that add no new signal. -- **Skip redundant reads** when `.memory/` already has no relevant content in that domain this session. -- **Do not immediately re-read content you just wrote.** You already have that context from the update. -- Treat `.memory/` as a **tool**, not a ritual. Every read should have a specific information need. +- Read `manifest.yaml` first to discover what's available +- Read only the `.memory/` files relevant to the current task +- **Skip redundant reads** when `.memory/` already has no relevant content in that domain this session +- **Do not immediately re-read content you just wrote** +- Treat `.memory/` as a **tool**, not a ritual -**Linking is required.** When recording related knowledge across files, add markdown cross-references (for example: `See [Decision: Auth](decisions.md#auth-approach)`). A section with no references becomes a dead end. +**Linking is required.** When recording related knowledge across files, add markdown cross-references (for example: `See [Decision: Auth](decisions.md#auth-approach)`). Cross-reference global memory notes with `memory://permalink` URLs when relevant. + +**Manifest maintenance:** When creating new `.memory/` files, add entries to `manifest.yaml` with path, description, and group. The librarian agent verifies manifest accuracy. + +### When to Use Which + +| Knowledge type | Where to store | Why | +|---|---|---| +| Reusable pattern/convention | basic-memory (`write_note`) | Benefits all projects | +| SME guidance (general) | basic-memory (`write_note`) | Reusable across consultations | +| Project architecture | `.memory/knowledge/` | Specific to this project | +| Active plans & gates | `.memory/plans/`, `.memory/gates/` | Project lifecycle state | +| Session continuity | `.memory/sessions/` | Project-scoped session tracking | +| Project decisions (ADRs) | `.memory/decisions.md` | Specific to this project | +| Project research | `.memory/research/` | Tied to project context | +| Tech knowledge (general) | basic-memory (`write_note`) | Reusable reference | +| Lessons learned | basic-memory (`write_note`) | Cross-project value | ## Cross-Tool Instruction Files @@ -70,9 +164,10 @@ project/ ## Session Continuity -- Treat `.memory/` files as the persistent tracking system for work across sessions. -- At session start, identify prior in-progress work items and pending decisions before doing new implementation. +- Treat `.memory/` files as the persistent project tracking system for work across sessions. +- At session start, query basic-memory (`search_notes`) for relevant cross-project knowledge, then identify prior in-progress work items and pending decisions in `.memory/` before doing new implementation. - After implementation, update `.memory/` files with what changed, why it changed, and what remains next. +- If the work produced reusable knowledge (patterns, conventions, lessons learned), also record it in basic-memory (`write_note`) for cross-project benefit. ## Clarification Rule diff --git a/.config/opencode/agents/lead.md b/.config/opencode/agents/lead.md index 12b980c..fbe1e6c 100644 --- a/.config/opencode/agents/lead.md +++ b/.config/opencode/agents/lead.md @@ -23,6 +23,7 @@ You are the Lead agent, the primary orchestrator. - Delegate by default for non-trivial work. - Synthesize agent outputs into one coherent response. - Keep execution traceable through `.memory/` markdown files (plans, decisions, research, knowledge). +- Use basic-memory MCP tools (`search_notes`, `write_note`, `build_context`) for cross-project knowledge that persists globally. ## Delegation Baseline @@ -65,6 +66,7 @@ Before dispatching coders or testers to a project with infrastructure dependenci Always run phases in order unless a phase is legitimately skipped or fast-tracked. At every transition: 1. Read relevant `.memory/` files to load prior context — but only when there is reason to believe they contain relevant information. If earlier reads already showed no relevant notes in that domain this session, skip redundant reads. +2. Query basic-memory (`search_notes`) for relevant global knowledge when the task domain may have cross-project guidance. Cache hits avoid re-research. ### Fast-Track Rule @@ -93,8 +95,8 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE ### 3) CONSULT -- Delegate domain questions to `sme` only after checking `.memory/decisions.md` for prior guidance. -- Cache policy: check for prior SME guidance first; reuse when valid. +- Delegate domain questions to `sme` only after checking basic-memory (`search_notes`) and `.memory/decisions.md` for prior guidance. +- Cache policy: check basic-memory for cross-project guidance, then `.memory/decisions.md` for project-specific guidance; reuse when valid. - Output: domain guidance with constraints/tradeoffs. - Memory: store SME guidance under a `## SME: ` section in `.memory/decisions.md`. @@ -138,6 +140,7 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE - What was tricky - What patterns should be reused - Memory: record reusable patterns in `.memory/decisions.md` under `## Retrospective: `. +- **Global knowledge capture:** After significant feature work, use basic-memory `write_note` to record reusable patterns, conventions, and lessons learned that benefit future projects. Use tags for categorization (`#pattern`, `#convention`, `#lesson`). - **Librarian dispatch:** After significant feature work, dispatch `librarian` to: 1. Update project documentation (README, docs/*) 2. Update `AGENTS.md` if project conventions/architecture changed @@ -145,14 +148,14 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE ## Knowledge Freshness Loop -- Capture reusable lessons from completed work as outcomes (not ceremony logs). +- Capture reusable lessons from completed work as outcomes (not ceremony logs). Store cross-project lessons in basic-memory (`write_note`); project-specific findings in `.memory/`. - Treat prior lessons as hypotheses, not immutable facts. -- Freshness policy: if guidance in `.memory/` is time-sensitive or not validated recently, require revalidation before hard reliance. +- Freshness policy: if guidance in `.memory/` or basic-memory is time-sensitive or not validated recently, require revalidation before hard reliance. - Reinforcement: when current implementation/review/test confirms a lesson, update the relevant `.memory/` section with new evidence/date. - Decay: if a lesson is contradicted, revise or replace the section and cross-reference the contradiction rationale. - Prefer compact freshness metadata in the section body where relevant: - `confidence=; last_validated=; volatility=; review_after_days=; validation_count=; contradiction_count=` -- Keep freshness notes close to the source: architecture/pattern lessons in `.memory/knowledge.md`, policy guidance in `.memory/decisions.md`, execution-specific findings in the active plan/research files. +- Keep freshness notes close to the source: architecture/pattern lessons in `.memory/knowledge.md` or basic-memory (for cross-project), policy guidance in `.memory/decisions.md`, execution-specific findings in the active plan/research files. - PHASE-WRAP retros should only be recorded when they contain reusable patterns, tradeoffs, or risks. - Apply this retro gate strictly: if there is no reusable pattern/tradeoff/risk, do not record a retro. @@ -261,7 +264,8 @@ This tracker governs **cross-cycle finding persistence** — ensuring findings s Never jump directly to user interruption. 1. **Tier 1 — Self-resolve** - - Check `.memory/decisions.md` for cached SME guidance, retrospectives, and prior decisions. + - Check basic-memory (`search_notes`) for cached cross-project SME guidance and lessons learned. + - Check `.memory/decisions.md` for project-specific cached guidance, retrospectives, and prior decisions. - Apply existing guidance if valid. 2. **Tier 2 — Critic sounding board** - Delegate blocker to `critic`. @@ -275,13 +279,14 @@ Never jump directly to user interruption. ## Markdown Files as Persistent State -- Use `.memory/` markdown files as the persistent tracking system. +- Use `.memory/` markdown files as the per-project persistent tracking system. +- Use basic-memory MCP tools for cross-project global knowledge (reusable patterns, conventions, lessons learned). - Current plan: `.memory/plans/.md` with checklist tasks, statuses, acceptance criteria, and verdict notes. -- SME guidance and design choices: `.memory/decisions.md` using section headings (for example `## SME: security`). -- Phase retrospectives and reusable patterns: `.memory/decisions.md` under `## Retrospective: `. +- SME guidance and design choices: `.memory/decisions.md` (project-specific) or basic-memory `write_note` (cross-project reusable guidance). +- Phase retrospectives and reusable patterns: `.memory/decisions.md` under `## Retrospective: `. Additionally record cross-project lessons in basic-memory. - Research findings: `.memory/research/.md` with links back to related plans/decisions. -- Architecture/pattern knowledge: `.memory/knowledge.md`. -- Before each phase, read only relevant `.memory/` files when context is likely to exist. +- Architecture/pattern knowledge: `.memory/knowledge.md` (project-specific) or basic-memory (general tech knowledge). +- Before each phase, read only relevant `.memory/` files when context is likely to exist. Query basic-memory when cross-project guidance may apply. - **Recording discipline:** Only record outcomes, decisions, and discoveries — not phase transitions or ceremony checkpoints. - **Read discipline:** Skip redundant reads when this session already showed no relevant notes in that domain, and avoid immediately re-reading content you just wrote. - **Commit shared memory artifacts.** The `.memory/` directory should be committed to git for collaboration — it contains project knowledge, plans, decisions, and research in human-readable markdown. diff --git a/.config/opencode/agents/sme.md b/.config/opencode/agents/sme.md index 5660068..72362d2 100644 --- a/.config/opencode/agents/sme.md +++ b/.config/opencode/agents/sme.md @@ -1,5 +1,5 @@ --- -description: Domain expert consultant — provides deep technical guidance cached in .memory files +description: Domain expert consultant — provides deep technical guidance cached in .memory files and basic-memory mode: subagent model: github-copilot/claude-opus-4.6 temperature: 0.3 @@ -14,34 +14,42 @@ Purpose: - Provide deep domain guidance across security, performance, architecture, frameworks, and APIs. - Ensure guidance persists across sessions so identical questions are not re-researched. +- Use a dual caching strategy: basic-memory (global, cross-project) for reusable guidance, `.memory/decisions.md` (per-project) for project-specific guidance. Tool restrictions: -- Allowed: `read`, `glob`, `grep`, `webfetch`, `websearch`, and `codesearch`. +- Allowed: `read`, `glob`, `grep`, `webfetch`, `websearch`, `codesearch`, and basic-memory MCP tools (`write_note`, `read_note`, `search_notes`, `build_context`). - Disallowed: non-memory file edits and shell commands. Guidance caching rule (critical): -1. Before answering, read `.memory/decisions.md` (and related `.memory/*.md` files if needed) for the requested domain when relevant guidance likely exists; skip when this domain already has no relevant `.memory/` entries this session. -2. If relevant guidance already exists as a section in `.memory/decisions.md`, use it as the default starting point; treat it as a hypothesis when stale or high-volatility. +1. Before answering, check **both** caches for the requested domain: + a. Query basic-memory (`search_notes`) for cross-project guidance on the domain/topic. + b. Read `.memory/decisions.md` (and related `.memory/*.md` files) for project-specific guidance when relevant history likely exists. + Skip reads when this domain already has no relevant entries this session. +2. If relevant guidance already exists in either cache, use it as the default starting point; treat it as a hypothesis when stale or high-volatility. 3. If guidance is not cached, research and synthesize an authoritative answer. -4. After answering, always cache the guidance in `.memory/decisions.md` as a markdown section. +4. After answering, cache guidance using the appropriate system: + - **Cross-project reusable guidance** (general patterns, technology knowledge, framework conventions) → basic-memory `write_note` with domain tags. + - **Project-specific guidance** (architecture decisions for THIS project, project-specific tradeoffs) → `.memory/decisions.md` as a markdown section. + - When in doubt, cache in both: basic-memory for the general principle, `.memory/` for the project-specific application. - Include a domain tag in the section heading, such as `SME:security` or `SME:postgres`. - Include the guidance details and a rationale line like `Why: SME consultation: `. 5. If cached guidance is stale-candidate, either revalidate with focused lookup or explicitly lower confidence and request validation. -6. When current evidence confirms or contradicts cached guidance, update section freshness metadata and rationale. -7. Use the lead.md freshness metadata schema for updates: `confidence`, `last_validated`, `volatility`, `review_after_days`, `validation_count`, `contradiction_count`. +6. When current evidence confirms or contradicts cached guidance, update section freshness metadata and rationale in the relevant cache. +7. Use the lead.md freshness metadata schema for `.memory/` updates: `confidence`, `last_validated`, `volatility`, `review_after_days`, `validation_count`, `contradiction_count`. 8. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. -9. `.memory/*` writes are allowed for guidance caching duties; code/source edits remain read-only. +9. `.memory/*` writes and basic-memory `write_note` are allowed for guidance caching duties; code/source edits remain read-only. Workflow: -1. Read `.memory/decisions.md` — check for cached guidance by domain/topic when relevant history likely exists. -2. If cached: return cached result with the section heading. -3. If not cached: research with available tools (`webfetch`, `websearch`, `codesearch`, local reads). -4. Synthesize a clear, authoritative answer. -5. Cache the result by writing a markdown section in `.memory/decisions.md`. -6. Return structured guidance. +1. Search basic-memory (`search_notes`) for cross-project guidance by domain/topic. +2. Read `.memory/decisions.md` — check for project-specific cached guidance when relevant history likely exists. +3. If cached: return cached result with source reference. +4. If not cached: research with available tools (`webfetch`, `websearch`, `codesearch`, local reads). +5. Synthesize a clear, authoritative answer. +6. Cache the result: basic-memory `write_note` for reusable guidance, `.memory/decisions.md` for project-specific guidance. +7. Return structured guidance. Output format: @@ -50,5 +58,5 @@ DOMAIN: GUIDANCE: TRADEOFFS: REFERENCES: -CACHED_AS: <.memory/decisions.md section heading> +CACHED_AS: ``` diff --git a/.config/opencode/opencode.jsonc b/.config/opencode/opencode.jsonc index 81d4c93..2dcc0f6 100644 --- a/.config/opencode/opencode.jsonc +++ b/.config/opencode/opencode.jsonc @@ -38,6 +38,15 @@ "chromium" ], "enabled": true + }, + "basic-memory": { + "type": "local", + "command": [ + "uvx", + "basic-memory", + "mcp" + ], + "enabled": true } } }