session-brain
编码会话的持久工作记忆。自动跟踪您正在做的事情、为什么这样做、做出的决定以及接下来要做什么。触发短语:-“从我们上次停下的地方继续”-“我们在做什么?”-“回顾一下这个存储库”/“赶上我”-“记住这个决定:...”-“我们为什么决定...”/“...的理由是什么”-“下一步是什么?” /“我应该做什么?”-“有哪些悬而未决的问题?”-“将其保存为项目规则”
name: session-brain description: | Persistent working memory for coding sessions. Automatically tracks what you're doing, why you're doing it, decisions made, and what's next.
Trigger phrases: - "resume where we left off" - "what were we doing?" - "recap this repo" / "catch me up" - "remember this decision: ..." - "why did we decide to ..." / "what was the rationale for ..." - "what's next?" / "what should I work on?" - "what are the open questions?" - "save this as a project rule" allowed-tools: - Read - Write - Grep - Glob - Bash
Session Brain
Persistent per-repo working memory stored under .claude/voyager/.
State Files
| File | Purpose |
|---|---|
brain.json |
Canonical structured state (validated against schema) |
brain.md |
Human-readable summary for quick reference |
episodes/ |
Per-session summaries for history |
How It Works
Session Brain updates automatically via hooks:
- SessionStart: Injects current brain context + repo snapshot
- PreCompact/SessionEnd: Persists changes to brain.json and creates episode
You don't need to manually update the brain—just work normally and it tracks context.
Reading brain.json
When exploring brain.json, use jq to query specific sections instead of reading the whole file:
# Current context (goal, plan, questions)
jq '.working_set' .claude/voyager/brain.json
# Decision history
jq '.decisions' .claude/voyager/brain.json
# Recent progress
jq '.progress' .claude/voyager/brain.json
# Project overview
jq '.project' .claude/voyager/brain.json
For a quick human-readable summary, read .claude/voyager/brain.md instead.
Answering User Questions
When users ask about context, read and interpret the brain files:
"Resume" / "What were we doing?"
- Read
.claude/voyager/brain.mdfor quick context - Check
brain.json→working_set.current_goalandworking_set.current_plan - Summarize: current goal, plan progress, any open questions
"What's next?"
- Read
brain.json→working_set.current_plan - Check
progress.recent_changesto see what's done - Suggest the next uncompleted step from the plan
"Why did we decide X?" / "What was the rationale?"
- Read
brain.json→decisionsarray - Find matching decision by keyword
- Return the
rationaleandimplications
"What are the open questions?"
- Read
brain.json→working_set.open_questions - Also check
working_set.risksfor blockers
Recording Decisions
When the user says "remember this decision: ..." or explicitly wants to record a decision:
- Read current
.claude/voyager/brain.json - Append to the
decisionsarray:{ "when": "<ISO timestamp>", "decision": "<what was decided>", "rationale": "<why>", "implications": ["<what this affects>"] } - Write updated
brain.json
Note: brain.md will be re-rendered automatically on the next session end or compaction.
Brain Schema Overview
See schemas/brain.schema.json for full schema. Key sections:
- project: Stable project understanding (summary, stack, key commands)
- working_set: Current context (goal, plan, open questions, risks)
- decisions: Append-only decision log with rationale
- progress: Recent changes and completed milestones
- signals: Metadata (last session ID, timestamp)
Technical Details
See reference.md for:
- Full file structure
- Update flow details
- Manual operations (reset, view history)
- Graceful degradation behavior