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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user