feat: replace megamemory with markdown-based memory system

Remove the megamemory MCP knowledge graph and replace with plain
markdown files in .memory/ for tracking plans, research, knowledge,
and implementation state. This enables collaboration across people
and agentic coding tools (Claude Code, Copilot, Cursor, etc.).

Changes:
- Remove megamemory MCP from opencode.jsonc
- Delete tool/megamemory.ts and .megamemory/ database
- Rewrite all 25 config files to use .memory/ markdown files
- Add cross-tool instruction file awareness (AGENTS.md, CLAUDE.md,
  copilot-instructions.md, .cursorrules)
- Update save-memory, bootstrap-memory, status commands for md workflow
- Update all agent files, skills, and commands consistently
This commit is contained in:
2026-03-08 18:43:46 +00:00
parent 2acdb86e3d
commit 204bbb4c84
27 changed files with 289 additions and 365 deletions

View File

@@ -1,30 +1,56 @@
## Project Knowledge Graph
## Project Memory
You have access to a project knowledge graph via the `megamemory` MCP server and skill tool. You have no implicit memory of this project between sessions, so this graph is your only continuity for concepts, architecture, decisions, and relationships.
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.
**Workflow: understand → work → update**
**Directory structure:**
1. **Session start:** You must call `megamemory` with action `overview` (or `megamemory:list_roots` directly) before you begin work.
2. **Before each task:** You must call `megamemory` with action `query` (or `megamemory:understand` directly) before reading source files for project understanding.
3. **After each task:** You must call `megamemory` with action `record` to create/update/link concepts for what you built.
```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
```
Be specific in summaries: include parameter names, defaults, file locations, and rationale. Keep concepts max 3 levels deep.
**Workflow: read files → work → update files**
**Recording discipline:** Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If a concept would only say "we started phase X", don't create it. Megamemory exists to preserve *knowledge*, not to log *activity*.
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.
**Query discipline:**
- Use `top_k=3` for `megamemory:understand` calls unless you have a specific reason to retrieve more. Large result sets bloat context without proportional value.
- **Skip `understand` when the graph has no relevant content.** If `list_roots` already showed no concepts in the relevant domain, do not call `understand` with rephrased queries hoping for different results.
- **Never re-query concepts you just created.** After calling `create_concept`, you already know the content — do not immediately call `understand` to retrieve it.
- Treat megamemory as a **tool**, not a ritual. Every query should have a specific information need; if you cannot articulate what you expect to find, skip the query.
Be specific in summaries: include parameter names, defaults, file locations, and rationale. Keep concepts organized as markdown sections (`## Heading`) and keep hierarchy shallow.
**Linking is required.** When creating or updating concepts, always create edges (`megamemory:link`) to related existing concepts. A concept with no edges is a dead end — always ask: *"What existing concept does this depend on, implement, or connect to?"* and link accordingly.
**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.
**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.
## Cross-Tool Instruction Files
- Maintain tool-specific instruction files so multiple agentic coding tools share the same project working context.
- Required instruction files:
- `AGENTS.md` (OpenCode)
- `CLAUDE.md` (Claude Code)
- `.github/copilot-instructions.md` (GitHub Copilot)
- `.cursorrules` (Cursor)
- These files should contain the same core project knowledge: purpose, stack, conventions, commands, and structure.
- `.memory/knowledge.md` is the source of truth; instruction files are derived views for tool consumption.
- When project knowledge changes significantly, update **all** cross-tool instruction files.
- When initializing or bootstrapping a project, create **all** cross-tool instruction files.
- Do not duplicate `.memory/` internals in these files; they describe how to work with the project, not project tracking state.
## Session Continuity
- Treat megamemory as the persistent tracking system for work across sessions.
- 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.
- After implementation, record what changed, why it changed, and what remains next.
- After implementation, update `.memory/` files with what changed, why it changed, and what remains next.
## Clarification Rule
@@ -49,7 +75,7 @@ Be specific in summaries: include parameter names, defaults, file locations, and
## Parallelization
- **Always parallelize independent work.** Any tool calls that do not depend on each other's output must be issued in the same message as parallel calls — never sequentially. This applies to bash commands, file reads, subagent delegations, and megamemory queries alike.
- **Always parallelize independent work.** Any tool calls that do not depend on each other's output must be issued in the same message as parallel calls — never sequentially. This applies to bash commands, file reads, and subagent delegations alike.
- Before issuing a sequence of calls, ask: *"Does call B require the result of call A?"* If not, send them together.
## Human Checkpoint Triggers