claude-memory
A persistent knowledge vault plugin for Claude Code. Every Claude Code session starts with a blank context — no memory of what you debugged last week, what decisions you made, or what gotchas you already discovered. This plugin gives Claude a growing knowledge base it reads at session start and writes to continuously, so knowledge compounds across sessions instead of resetting.
The Problem
Claude starts every session from scratch. The Remember plugin captures a raw event stream, but raw transcripts are not the same as compiled knowledge — they are noise with signal buried in them. You end up re-explaining context, re-discovering the same solutions, and repeating mistakes you already fixed.
This plugin maintains a vault of compiled, structured knowledge that Claude reads at session start. New findings get distilled into the vault during and after each session. The signal accumulates; the noise stays out.
Architecture
Remember (raw stream) --> Reflect (session end) --> brain/ (compiled) --> SessionStart (orientation)
- Remember captures a raw transcript of each session automatically.
- Reflect and wrap-up read that transcript, extract durable knowledge, and write it to the vault.
- brain/ holds compiled accumulators: goals, decisions, patterns, gotchas, and skills. These are what Claude reads at the start of each new session to orient itself.
- SessionStart hook runs
session-orient.sh, which loads brain/goals.md and brain/skills.md into context and prints a one-line orientation summary.
The vault itself is a folder of plain Markdown files in an Obsidian vault. No cloud services, no lock-in.
Quick Start
claude plugin install claude-memory
Or load from a local clone:
claude --plugin-dir /path/to/claude-memory
Then, in your first session with Claude Code:
/claude-memory:init
/claude-memory:standup
/claude-memory:init scaffolds the vault folder structure and copies templates. /claude-memory:standup reads brain/ and gives you a briefing on current goals and recent context.
Prerequisites:
- Obsidian installed with a vault
- Python 3.8+ (for hook scripts)
- git (for vault version control)
Optional (recommended):
- Nexus MCP for semantic search:
claude mcp add nexus -- node <vault>/.obsidian/plugins/nexus/connector.js
- Remember plugin for automatic session capture:
claude plugin install remember
The plugin degrades gracefully when Nexus or Remember are unavailable.
Daily Workflow
| Phase | Action |
|---|
| Session start | Run /claude-memory:standup — get a briefing on goals and recent context |
| During work | Ambient capture happens automatically via hooks — no action needed |
| Explicit capture | Say "vault this" or "remember this" to capture something specific |
| Freeform capture | Run /claude-memory:dump to brain-dump notes, links, or observations |
| Session end | Run /claude-memory:wrap-up — prompts wrap-up checklist and updates brain/ |
| Between sessions | brain/ persists; next standup reads it cold |
Hook Pipeline
| Hook | Trigger | What it does |
|---|
SessionStart | Session opens | Runs session-orient.sh: reads brain/goals.md and brain/skills.md, prints orientation summary |
UserPromptSubmit | Each user message | Runs classify-message.py: detects 9 signal categories (DECISION, SOLUTION, GOTCHA, FUTURE, etc.) and injects routing hints for vault note creation |
PostToolUse | After Write or Edit | Runs validate-write.py: checks that new vault notes have required frontmatter fields for their tier |
PreCompact | Before context compaction | Runs pre-compact.sh: backs up the current transcript excerpt to thinking/ so Reflect can read it after compaction |
Stop | Session ends | Prints the session end checklist: run wrap-up, run reflect, check for orphan notes |
brain/ Layer
The brain/ folder holds compiled knowledge accumulators. Claude reads and updates these, not the user. Do not manually edit unless you want to seed initial content.
| File | What it stores |
|---|
brain/index.md | Recent context: last session summary, active threads, open questions |
brain/goals.md | Current focus areas and priorities. Read at every session start. |
brain/decisions.md | Log of non-obvious choices with rationale and date. Linked to full decision notes. |
brain/patterns.md | Recurring patterns Claude has observed across sessions |
brain/gotchas.md | Known failure modes, surprises, and things that bite. Consulted before major work. |
brain/skills.md | Available skills, agents, and tools Claude knows about for this vault |
During /claude-memory:reflect and /claude-memory:wrap-up, Claude appends new entries to the relevant accumulators and updates brain/index.md with a session summary.
Schema
xrf9268-hue
JuliusBrussee
wshobson
alirezarezvani
