alex/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: integrate basic-memory MCP for dual memory system

Browse Source 
Add basic-memory as a global cross-project knowledge store alongside
the existing per-project .memory/ system. Agents can now persist
reusable patterns, conventions, and lessons learned across all projects
via MCP tools (write_note, search_notes, build_context).

Changes:
- opencode.jsonc: add basic-memory MCP server config
- AGENTS.md: rewrite Project Memory section for dual system with
  routing table (global vs per-project)
- agents/lead.md: integrate basic-memory into phase transitions,
  CONSULT, PHASE-WRAP, escalation, and knowledge freshness
- agents/sme.md: dual caching strategy (basic-memory for cross-project
  guidance, .memory/ for project-specific)
This commit is contained in:
alex
2026-03-09 17:33:04 +00:00
parent 6727c91889
commit 457fb2068b
4 changed files with 163 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
.config/opencode/AGENTS.md
View File

@@ -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
<feature>.md # Plan with tasks, statuses, acceptance criteria
research/ # Research findings
<topic>.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)
│ └── <feature>.md
│
├── research/ # Project-specific research findings
│ └── <topic>.md
│
├── gates/ # Quality gate records
│ └── <feature>.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/<feature>.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: <project-name>
version: 1
categories:
- path: <relative-path>
description: <one-line description>
group: <knowledge|decisions|plans|research|gates|sessions>
```
**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