alex
e9074646b7
Replace 4 separate instruction files with 1 real file + symlinks: - .github/copilot-instructions.md is the canonical instruction file - CLAUDE.md and .cursorrules are symlinks to it - AGENTS.md stays as global config (not a project instruction file) This eliminates all sync/merge logic - changes propagate automatically. Changes: - AGENTS.md: rewrite Cross-Tool Instruction Files section for symlink convention - librarian.md: simplify to maintain single instruction file + verify symlinks - lead.md: simplify PHASE-WRAP and Documentation Completion Gate - commands (init, bootstrap-memory, save-memory): update for symlink model - doc-coverage skill: verify symlinks exist and point correctly
2.8 KiB
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 .github/copilot-instructions.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.