# 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.