feat: integrate basic-memory MCP for dual memory system

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)

.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
-    <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
 

.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: <domain>` 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: <topic>`.
+- **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=<high|medium|low>; last_validated=<YYYY-MM-DD>; volatility=<low|medium|high>; review_after_days=<n>; validation_count=<n>; contradiction_count=<n>`
-- 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/<feature>.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: <topic>`.
+- 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: <topic>`. Additionally record cross-project lessons in basic-memory.
 - Research findings: `.memory/research/<topic>.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.

.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: <domain>`.
 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: <domain>
 GUIDANCE: <detailed answer>
 TRADEOFFS: <key tradeoffs if applicable>
 REFERENCES: <sources if externally researched>
-CACHED_AS: <.memory/decisions.md section heading>
+CACHED_AS: <basic-memory note title and/or .memory/decisions.md section heading>
 ```

.config/opencode/opencode.jsonc

@@ -38,6 +38,15 @@
 				"chromium"
 			],
 			"enabled": true
+		},
+		"basic-memory": {
+			"type": "local",
+			"command": [
+				"uvx",
+				"basic-memory",
+				"mcp"
+			],
+			"enabled": true
 		}
 	}
 }