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

title, type, permalink

title	type	permalink
save-memory	note	opencode-config/commands/save-memory

Save Session Knowledge

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: Identify the per-repo basic-memory project

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 .memory/ subdirectory as project_path (e.g., /path/to/repo/.memory).

All project-specific notes must target project="<repo-project-name>". Cross-project reusable knowledge must target project="main".

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?
• What features, modules, or components did you build or change?
• What design or architectural decisions were made and why?
• What patterns or conventions did you discover?
• What research findings are worth keeping?
• Did anything get removed, replaced, or deprecated?

Step 4: Map learnings to notes (with correct project target)

For each thing worth remembering, write or update the right note in the right project:

• 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

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.

Prefer updating existing notes over creating duplicates.

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 WikiLink cross-references to related notes

Step 6: Verify and report

Use search_notes (with project) to confirm notes reflect current understanding. Report what was added/updated, where, and in which project.

Step 7: Update instruction file if project knowledge changed

If project knowledge/ notes were materially updated (architecture, conventions, commands — not just plans/research), update AGENTS.md to reflect the changes. Keep repo instruction guidance in AGENTS.md only.

If updates were only plans/research/tracking details, skip this step.

Guidelines

• 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".
• 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.