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,83 +1,79 @@
|
||||
# Save Session Knowledge
|
||||
|
||||
You are saving what you learned this session into the megamemory knowledge graph.
|
||||
You are saving what you learned this session into the project's `.memory/` directory.
|
||||
This is YOUR memory — record anything valuable for future sessions: what you
|
||||
understood about the project, what you built, decisions that were made, patterns
|
||||
you noticed, or intent the user shared.
|
||||
|
||||
## Step 1: Load existing graph
|
||||
## Step 1: Load existing memory files
|
||||
|
||||
Call `megamemory:list_roots` to see what's already recorded. Understanding the
|
||||
current state prevents duplicates and helps you decide what to update vs create.
|
||||
Read the `.memory/` directory and existing files to see what's already recorded.
|
||||
At minimum, check:
|
||||
- `.memory/knowledge.md`
|
||||
- `.memory/decisions.md`
|
||||
- `.memory/plans/*.md`
|
||||
- `.memory/research/*.md`
|
||||
|
||||
Understanding current state prevents duplication and helps you decide what to update.
|
||||
|
||||
## Step 2: Reflect on this session
|
||||
|
||||
Think about what happened this session. Consider:
|
||||
- What did you learn about the project's purpose or intent?
|
||||
- What features, modules, or components did you build or change?
|
||||
- What design decisions were made and why?
|
||||
- What design or architectural decisions were made and why?
|
||||
- What patterns or conventions did you discover?
|
||||
- What architectural understanding do you have now that isn't in the graph?
|
||||
- What research findings are worth keeping?
|
||||
- Did anything get removed, replaced, or deprecated?
|
||||
|
||||
## Step 3: Search for overlap
|
||||
## Step 3: Map learnings to memory files
|
||||
|
||||
Before creating anything new, call `megamemory:understand` with queries based on
|
||||
what you worked on this session. For each area you touched, search to see if
|
||||
concepts already exist that should be updated rather than duplicated.
|
||||
For each thing worth remembering, update the right file:
|
||||
|
||||
For example, if you worked on authentication, call:
|
||||
megamemory:understand — query="authentication"
|
||||
- **Project architecture/patterns/conventions** → `.memory/knowledge.md`
|
||||
- **Decisions and rationale** → `.memory/decisions.md`
|
||||
- **Ongoing feature plans and acceptance criteria** → `.memory/plans/<feature>.md`
|
||||
- **Deep research findings** → `.memory/research/<topic>.md`
|
||||
|
||||
Do this for each distinct area. Existing concepts that are stale or incomplete
|
||||
should be updated — don't create a new node when an update will do.
|
||||
Prefer updating existing sections over creating duplicates.
|
||||
|
||||
## Step 4: Write to the knowledge graph
|
||||
## Step 4: Write updates using markdown sections
|
||||
|
||||
For each thing worth remembering:
|
||||
Use standard markdown headings (`##`) and concise subsections when needed.
|
||||
Do not use concept IDs or graph-style metadata.
|
||||
|
||||
**New understanding** → `megamemory:create_concept`
|
||||
- name: human-readable name
|
||||
- kind: use `decision` for intent/rationale, `feature` for capabilities,
|
||||
`module` for subsystems, `pattern` for conventions, `config` for setup,
|
||||
`component` for distinct pieces of a system
|
||||
- summary: be specific — include parameter names, defaults, file paths,
|
||||
behavior details, and the WHY behind things
|
||||
- why: the rationale — this is often the most valuable part
|
||||
- file_refs: relevant files if applicable
|
||||
- edges: connect to existing concepts where relationships exist
|
||||
[{to: "concept-id", relation: "depends_on|implements|calls|connects_to|configured_by", description: "why"}]
|
||||
- created_by_task: brief description of what you were doing this session
|
||||
When writing, be specific:
|
||||
- include parameter names, defaults, file paths, behavior details
|
||||
- include rationale (`why`) for decisions
|
||||
- include cross-references to related memory entries
|
||||
|
||||
**Updated understanding** → `megamemory:update_concept`
|
||||
- id: the concept slug
|
||||
- changes: {summary?, why?, file_refs?, name?, kind?}
|
||||
If an existing concept is now stale or incomplete based on what you learned,
|
||||
update it. This is often more valuable than creating new nodes.
|
||||
Example cross-reference:
|
||||
- `See [Decision: Auth token TTL](../decisions.md#decision-auth-token-ttl)`
|
||||
|
||||
**New connections** → `megamemory:link`
|
||||
- from, to: concept IDs
|
||||
- relation: depends_on | implements | calls | connects_to | configured_by
|
||||
- description: why this relationship exists
|
||||
If you discovered how existing concepts relate to each other.
|
||||
## Step 5: Verify and report
|
||||
|
||||
**Removed/replaced things** → `megamemory:remove_concept`
|
||||
- id: concept to remove
|
||||
- reason: why it was removed
|
||||
If something in the graph is no longer true.
|
||||
Re-read updated `.memory/` files to confirm they reflect current understanding.
|
||||
Report what was added/updated and where.
|
||||
|
||||
## Step 5: Verify
|
||||
## Step 6: Sync cross-tool instruction files when project knowledge changed
|
||||
|
||||
Call `megamemory:list_roots` again. Confirm the graph reflects your current
|
||||
understanding. Report what you saved.
|
||||
Check whether `.memory/knowledge.md` was **materially** updated in this save.
|
||||
Material updates include project-level changes such as architecture, conventions,
|
||||
or build/test/lint commands.
|
||||
|
||||
- If there was a material `knowledge.md` update:
|
||||
- Read current instruction files: `AGENTS.md`, `CLAUDE.md`,
|
||||
`.github/copilot-instructions.md`, `.cursorrules`
|
||||
- Update them to reflect the new core project knowledge while preserving
|
||||
tool-specific formatting and project-specific content.
|
||||
- If updates were only plans/research/tracking details (no project-level
|
||||
knowledge change), do **not** update instruction files.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Record what a future you (with no memory of this session) would need to know.
|
||||
- Intent and rationale ("why") are more valuable than implementation details.
|
||||
- Update existing concepts before creating new ones — keep the graph lean.
|
||||
- Don't record trivial things. If it's obvious from the code, skip it.
|
||||
- Max 2 levels of nesting. Flat is better than deep.
|
||||
- Connect concepts — isolated nodes are less useful than a connected graph.
|
||||
- Be specific. "Handles auth" is useless. "JWT auth with RS256, validated in
|
||||
middleware at src/middleware/auth.ts, refresh tokens in Redis with 7d TTL" is useful.
|
||||
- Outcomes and rationale are more valuable than ceremony.
|
||||
- Don’t log process-only updates like "started phase X".
|
||||
- Keep hierarchy shallow (max 2 heading levels preferred).
|
||||
- Be specific. "Handles auth" is weak. "JWT auth with RS256, validated in
|
||||
`src/middleware/auth.ts`, refresh tokens in Redis with 7d TTL" is useful.
|
||||
|
||||
Reference in New Issue
Block a user