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

Save Session Knowledge

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 memory files

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 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 3: Map learnings to memory files

For each thing worth remembering, update the right file:

• 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

Prefer updating existing sections over creating duplicates.

Step 4: Write updates using markdown sections

Use standard markdown headings (##) and concise subsections when needed. Do not use concept IDs or graph-style metadata.

When writing, be specific:

• include parameter names, defaults, file paths, behavior details
• include rationale (why) for decisions
• include cross-references to related memory entries

Example cross-reference:

• See [Decision: Auth token TTL](../decisions.md#decision-auth-token-ttl)

Step 5: Verify and report

Re-read updated .memory/ files to confirm they reflect current understanding. Report what was added/updated and where.

Step 6: Update instruction file if project knowledge changed

If .memory/knowledge.md was materially updated (architecture, conventions, commands — not just plans/research), update AGENTS.md to reflect the changes. The symlinks automatically propagate to all tools.

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.