changes

.config/opencode/commands/save-memory.md

@@ -1,22 +1,32 @@
+---
+title: save-memory
+type: note
+permalink: opencode-config/commands/save-memory
+---
+
 # Save Session Knowledge
 
-You are saving what you learned this session into the project's `.memory/` directory.
+You are saving what you learned this session into basic-memory notes.
 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 memory files
+## Step 1: Identify the per-repo basic-memory project
 
-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`
+Use `list_memory_projects` to find this repo's dedicated basic-memory project.
+If it doesn't exist, create one with `create_memory_project` using a short
+kebab-case name and the repo's root directory as `project_path`.
 
-Understanding current state prevents duplication and helps you decide what to update.
+All project-specific notes must target `project="<repo-project-name>"`.
+Cross-project reusable knowledge must target `project="main"`.
 
-## Step 2: Reflect on this session
+## Step 2: Load existing notes
+
+Use `search_notes` and `build_context` (with the correct `project`) to see
+what's already recorded. Understanding current state prevents duplication and
+helps you decide what to update.
+
+## Step 3: Reflect on this session
 
 Think about what happened this session. Consider:
 - What did you learn about the project's purpose or intent?
@@ -26,38 +36,37 @@ Think about what happened this session. Consider:
 - What research findings are worth keeping?
 - Did anything get removed, replaced, or deprecated?
 
-## Step 3: Map learnings to memory files
+## Step 4: Map learnings to notes (with correct project target)
 
-For each thing worth remembering, update the right file:
+For each thing worth remembering, write or update the right note in the right project:
 
-- **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`
+- **Project architecture/patterns/conventions** → per-repo project `knowledge/` notes (`project="<repo-project-name>"`)
+- **Decisions and rationale** → per-repo project `decisions/` notes (`project="<repo-project-name>"`)
+- **Ongoing feature plans and acceptance criteria** → per-repo project `plans/<feature>` notes (`project="<repo-project-name>"`)
+- **Deep research findings** → per-repo project `research/<topic>` notes (`project="<repo-project-name>"`)
+- **Reusable cross-project patterns, conventions, tech knowledge, lessons learned** → `project="main"` with appropriate tags
 
-Prefer updating existing sections over creating duplicates.
+**Hard rule:** Never store project-specific plans, decisions, research, gates, or sessions in `main`. Never store cross-project reusable knowledge in a per-repo project.
 
-## Step 4: Write updates using markdown sections
+Prefer updating existing notes over creating duplicates.
 
-Use standard markdown headings (`##`) and concise subsections when needed.
-Do not use concept IDs or graph-style metadata.
+## Step 5: Write updates
+
+Use `write_note` with appropriate folder, tags, WikiLinks, and **always the correct `project` parameter**.
 
 When writing, be specific:
 - include parameter names, defaults, file paths, behavior details
 - include rationale (`why`) for decisions
-- include cross-references to related memory entries
+- include WikiLink cross-references to related notes
 
-Example cross-reference:
-- `See [Decision: Auth token TTL](../decisions.md#decision-auth-token-ttl)`
+## Step 6: Verify and report
 
-## Step 5: Verify and report
+Use `search_notes` (with `project`) to confirm notes reflect current understanding.
+Report what was added/updated, where, and in which project.
 
-Re-read updated `.memory/` files to confirm they reflect current understanding.
-Report what was added/updated and where.
+## Step 7: Update instruction file if project knowledge changed
 
-## Step 6: Update instruction file if project knowledge changed
-
-If `.memory/knowledge.md` was **materially** updated (architecture, conventions,
+If project `knowledge/` notes were **materially** updated (architecture, conventions,
 commands — not just plans/research), update `AGENTS.md` to reflect the changes.
 The symlinks automatically propagate to all tools.
 
@@ -67,7 +76,8 @@ If updates were only plans/research/tracking details, skip this step.
 
 - Record what a future you (with no memory of this session) would need to know.
 - Outcomes and rationale are more valuable than ceremony.
-- Don’t log process-only updates like "started phase X".
+- 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.
+- Always pass the `project` parameter on every MCP call.