Skip to content

Persistent project knowledge graph for coding agents. MCP server with semantic search, in-process embeddings, and web explorer.

Add /save-memory command for persisting session knowledge

0xk3vin1c0fcff00b57
diff --git a/README.md b/README.md
index a07ba0b..d577fce 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,7 @@ One command configures everything:
- Workflow instructions in `~/.config/opencode/AGENTS.md`
- Skill tool plugin at `~/.config/opencode/tool/megamemory.ts`
- Bootstrap command `/user:bootstrap-memory` for initial graph population
+- Save command `/user:save-memory` to persist session knowledge
Restart opencode after running init.
@@ -138,6 +139,7 @@ plugin/
megamemory.ts Opencode skill tool plugin
commands/
bootstrap-memory.md /user command for initial population
+ save-memory.md /user command to save session knowledge
web/
index.html Single-file graph visualization (Cytoscape.js)
```
diff --git a/commands/save-memory.md b/commands/save-memory.md
new file mode 100644
index 0000000..b6f3bc4
--- /dev/null
+++ b/commands/save-memory.md
@@ -0,0 +1,83 @@
+# Save Session Knowledge
+
+You are saving what you learned this session into the megamemory knowledge graph.
+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
+
+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.
+
+## 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 patterns or conventions did you discover?
+- What architectural understanding do you have now that isn't in the graph?
+- Did anything get removed, replaced, or deprecated?
+
+## Step 3: Search for overlap
+
+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 example, if you worked on authentication, call:
+ megamemory:understand — query="authentication"
+
+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.
+
+## Step 4: Write to the knowledge graph
+
+For each thing worth remembering:
+
+**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
+
+**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.
+
+**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.
+
+**Removed/replaced things** → `megamemory:remove_concept`
+ - id: concept to remove
+ - reason: why it was removed
+ If something in the graph is no longer true.
+
+## Step 5: Verify
+
+Call `megamemory:list_roots` again. Confirm the graph reflects your current
+understanding. Report what you saved.
+
+## 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.
diff --git a/package-lock.json b/package-lock.json
index b1a418d..5c2a069 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "megamemory",
- "version": "1.1.1",
+ "version": "1.1.2",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "megamemory",
- "version": "1.1.1",
+ "version": "1.1.2",
"license": "MIT",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.1",
diff --git a/package.json b/package.json
index 67fc759..068da06 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "megamemory",
- "version": "1.1.1",
+ "version": "1.1.2",
"description": "MCP server that gives coding agents persistent project understanding via a knowledge graph",
"type": "module",
"main": "dist/index.js",
diff --git a/src/init.ts b/src/init.ts
index ed31650..d414a19 100644
--- a/src/init.ts
+++ b/src/init.ts
@@ -66,11 +66,11 @@ function resolvePluginSource(): string {
}
/**
- * Resolve absolute path to the commands/bootstrap-memory.md file.
+ * Resolve absolute path to a file in the commands/ directory.
*/
-function resolveCommandSource(): string {
+function resolveCommandFile(filename: string): string {
const thisDir = path.dirname(fileURLToPath(import.meta.url));
- return path.resolve(thisDir, "..", "commands", "bootstrap-memory.md");
+ return path.resolve(thisDir, "..", "commands", filename);
}
// ---- Setup steps ----
@@ -187,9 +187,9 @@ function setupToolPlugin(): void {
}
}
-function setupBootstrapCommand(): void {
- const source = resolveCommandSource();
- const dest = path.join(OPENCODE_COMMANDS_DIR, "bootstrap-memory.md");
+function setupCommand(filename: string, label: string): void {
+ const source = resolveCommandFile(filename);
+ const dest = path.join(OPENCODE_COMMANDS_DIR, filename);
if (!fs.existsSync(source)) {
skip(`Command source not found at ${pc.dim(source)}`);
@@ -205,14 +205,14 @@ function setupBootstrapCommand(): void {
if (fs.existsSync(dest)) {
const existing = fs.readFileSync(dest, "utf-8");
if (existing === sourceContent) {
- skip(`Bootstrap command already up to date`);
+ skip(`${label} already up to date`);
return;
}
fs.writeFileSync(dest, sourceContent);
- success(`Updated bootstrap command at ${pc.dim(dest)}`);
+ success(`Updated ${label} at ${pc.dim(dest)}`);
} else {
fs.writeFileSync(dest, sourceContent);
- success(`Installed bootstrap command at ${pc.dim(dest)}`);
+ success(`Installed ${label} at ${pc.dim(dest)}`);
}
}
@@ -273,7 +273,7 @@ export async function runInit(): Promise<void> {
// Step 4: Bootstrap command
heading(` 4. Bootstrap command`);
try {
- setupBootstrapCommand();
+ setupCommand("bootstrap-memory.md", "bootstrap command");
steps.push({ name: "Bootstrap command", ok: true });
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
@@ -283,12 +283,28 @@ export async function runInit(): Promise<void> {
console.log();
+ // Step 5: Save memory command
+ heading(` 5. Save memory command`);
+ try {
+ setupCommand("save-memory.md", "save memory command");
+ steps.push({ name: "Save memory command", ok: true });
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ error(`Save memory command setup failed: ${msg}`);
+ steps.push({ name: "Save memory command", ok: false, error: msg });
+ }
+
+ console.log();
+
// Summary
const failed = steps.filter((s) => !s.ok);
if (failed.length === 0) {
console.log(` ${pc.green(pc.bold("Done."))} Restart opencode to pick up changes.`);
console.log(
- pc.dim(` Run ${pc.cyan("/user:bootstrap-memory")} in any project to populate its knowledge graph.`)
+ pc.dim(` Run ${pc.cyan("/user:bootstrap-memory")} to populate a project's knowledge graph.`)
+ );
+ console.log(
+ pc.dim(` Run ${pc.cyan("/user:save-memory")} after a session to save what you learned.`)
);
} else {
console.log(