Parsidion: The Persistent Brain for Claude Code
user
~/Repos/parsidion
$
claude
A Claude Code customization toolkit that replaces built-in auto memory with a markdown vault-based knowledge management system, augmented by lifecycle hooks, a research agent, and graph-colorized vault exploration. Obsidian is optional — useful for visualization, not required.
- Automatic context loading at session start
- Learning capture from every session transcript
- AI-powered session summarization into structured notes
- Working state snapshots before context compaction
- Research agent that saves findings to the vault
Python 3.13+
stdlib only
Obsidian (optional)
config.yaml
System Architecture Overview
The system connects Claude Code's lifecycle events to a markdown vault through three hook scripts, a shared library, and an AI summarizer.
Four-Layer Architecture
Hooks → AI Summarizer → Shared Library → Markdown Vault
Layer 1: Hook Scripts
Python scripts fired by Claude Code lifecycle events. Communicate via JSON stdin/stdout.
- SessionStart — context injection
- SessionEnd — learning capture
- PreCompact — state snapshots
Layer 2: AI Summarizer
PEP 723 script using the configured CLI AI backend. Processes pending sessions into structured vault notes.
- Up to 5 parallel sessions
- Reads pending_summaries.jsonl
- Auto-launched by SessionEnd hook
Layer 3: vault_common.py
Shared library (stdlib-only). Frontmatter parsing, vault traversal, note search, path utilities.
- Regex-based YAML parser
- Config caching system
- Git commit integration
Layer 4: ~/ClaudeVault/
The markdown vault. Auto-generated index, cross-linked notes, domain-based graph colors (visualized via Obsidian — optional).
- 9 organized subfolders
- YAML frontmatter on every note
- Wikilink cross-references
SessionStart Hook: Context Injection
Load relevant vault knowledge into every new session
Session Begins
→
Detect Project
→
Gather Notes
→
Build Context
→
Inject
Standard Mode:
1. Determine project from working directory
2. Ensure vault dirs + today's daily note exist
3. Gather project-tagged notes (by frontmatter field)
4. Gather recent notes (last 3 days, configurable)
5. Deduplicate & budget to ~4000 chars
6. Return as additionalContext in hook output
AI-Powered Mode (--ai):
1. Collect ALL vault notes as candidates
2. Build summarised candidate block (~8000 chars)
3. Run claude -p with CLAUDECODE unset
4. Claude selects most relevant notes
5. Falls back to standard mode on timeout
max_chars: 4000
ai_timeout: 25s
recent_days: 3
Requires 30s hook timeout for AI mode
SessionEnd Hook: Learning Capture
Detect and preserve knowledge from every session
Keyword Detection
Scans last 200 transcript lines for four learning categories:
Error Fixes
Research
Patterns
Config/Setup
Keywords: "fixed", "root cause", "found that", "documentation says", "pattern", "best practice", "configured"...
Queue & Summarize
Significant sessions queued for AI summarization:
{"session_id": "abc-123",
"transcript_path": "/path/to/t.jsonl",
"project": "my-project",
"categories": ["error_fix", "pattern"],
"timestamp": "2026-03-12T14:30:00"}
Uses fcntl.flock for safe concurrent access
1
Read transcript & extract assistant messages
2
Run keyword heuristics (or AI classification with --ai)
3
Append session summary to today's daily note
4
Queue to pending_summaries.jsonl → auto-launch summarizer
SubagentStop Hook: Subagent Learning Capture
Harvest knowledge from every Agent tool invocation — asynchronously
What It Captures
Reads the subagent's own agent_transcript_path and queues it for AI summarization — identical pipeline to SessionEnd.
{"session_id": "abc-123",
"transcript_path": "...",
"source": "subagent",
"agent_type": "Explore",
"categories": ["pattern"]}
Smart Exclusions
Vault system agents are excluded to avoid recursive capture loops:
excluded_agents: "vault-explorer,
research-agent"
Configurable in config.yaml under subagent_stop_hook
1
SubagentStop fires — agent_transcript_path + agent_type provided
2
Check agent_type against excluded_agents list
3
Read full transcript & run keyword heuristics (no 200-line cap)
4
Queue to pending_summaries.jsonl (deduped by agent_id)
async: true
non-blocking
min_messages: 3
subagent_stop_hook.py
PreCompact Hook: State Snapshots
Preserve working context before Claude Code compacts memory
Context Full
→
Read Transcript
→
Extract Task
→
Extract Files
→
Write Snapshot
When Claude Code runs out of context window, it compacts the conversation. This hook fires before compaction, capturing what you were working on so the context survives.
Snapshot captures:
Current Task: Scans backward through last 200 lines
for the most recent user text message
Active Files: Parses tool_use blocks from assistant messages
(Read, Write, Edit, Grep, NotebookEdit)
Up to 15 file paths extracted
Output: Appends "## Pre-Compact Snapshot" section
to today's daily note in ~/ClaudeVault/Daily/YYYY-MM/DD.md
lines: 200
git auto-commit
Session Summarizer: AI Note Generation
Transform raw transcripts into structured vault knowledge
pending_summaries.jsonl
→
Pre-process
→
CLI AI backend (5x)
→
Save Notes
→
Reindex
How It Works
- PEP 723 script with inline deps (anyio)
- Pre-processes transcripts: extract human/assistant dialogue
- Up to 5 parallel CLI backend calls
- Generates notes with YAML frontmatter + wikilinks
- Cleans queue, rebuilds index, git commits
Configuration
| model | claude-sonnet-4-6 |
| max_parallel | 5 |
| tail_lines | 400 |
| max_chars | 12000 |
| persist | false |
Note: Must be run from a separate terminal (or with env -u CLAUDECODE)
when using the Claude CLI backend because nested Claude CLI invocations are blocked inside Claude Code.
vault_common.py: The Shared Core
stdlib-only library powering all vault operations
Note Operations
parse_frontmatter() # Regex YAML parser
get_body() # Content after frontmatter
ensure_note_index_schema() # Create note_index table+indexes
query_note_index() # DB query; None=fall back to walk
find_notes_by_project() # DB-first → file walk fallback
find_notes_by_tag() # DB-first → file walk fallback
find_notes_by_type() # DB-first → file walk fallback
find_recent_notes() # DB-first → file walk fallback
all_vault_notes() # All .md files
Infrastructure
build_context_block() # Char-budgeted context
get_project_name() # From cwd or git root
ensure_vault_dirs() # Create missing dirs
create_daily_note_..() # From template
slugify() # Kebab-case filenames
git_commit_vault() # Stage & commit
Configuration
load_config() # Load & cache YAML
get_config(sec,key,def) # Lookup with fallback
_parse_config_yaml() # stdlib YAML parser
_strip_inline_comment() # Handle # comments
Design Decisions
- No external dependencies — stdlib only
- Custom YAML parser via regex (no pyyaml)
- Excludes: .obsidian, Templates, .git, .trash, TagsRoutes
- Config cached per process lifetime
note_index: Fast Metadata Search
SQLite table in embeddings.db — sub-ms indexed queries vs O(n) file walks
Schema (note_index table)
stem TEXT PRIMARY KEY
path TEXT NOT NULL
folder TEXT -- e.g. "Debugging"
title TEXT
summary TEXT
tags TEXT -- comma-sep "python, sqlite"
note_type TEXT -- frontmatter 'type'
project TEXT
confidence TEXT
mtime REAL -- unix timestamp
related TEXT -- comma-sep stems
is_stale INTEGER 0|1
incoming_links INTEGER
5 indexes: folder, note_type, project, mtime DESC, tags
vault-search filter mode CLI
vault-search \
--tag python --folder Patterns
vault-search --recent-days 7
vault-search --type debugging
vault-search --project parsidion
# → [] gracefully when DB absent
# --json (default) or --text output
Population & Lifecycle
update_index.py upserts all rows on every rebuild
build_embeddings.py creates schema on first DB open
- Deleted notes pruned automatically
- All exceptions swallowed — never crashes indexer
- Exact tag-token LIKE pattern avoids false partial matches
707 notes indexed
stdlib-only
graceful fallback
The Markdown Vault: ~/ClaudeVault/
Structured knowledge base with 10 domain folders
~/ClaudeVault/
.obsidian/
config.yaml
CLAUDE.md
pending_summaries.jsonl
Daily/YYYY-MM/DD.md
Projects/
Languages/
Frameworks/
Patterns/
Debugging/
Tools/
Research/
History/
Templates/
Auto-Generated Index (CLAUDE.md)
- Quick Stats — total notes, last updated
- Tag Cloud — sorted by frequency
- Recent Activity — last 7 days (max 20)
- Folders — per-folder listings + summaries
8 Note Templates
daily
project
language
framework
pattern
debugging
tool
research
Templates/ is a symlink to the skill's templates/ folder
Vault Note Conventions
Every note follows strict formatting rules for consistency
---
date: 2026-03-12
type: pattern
tags: [claude-code, memory]
project: parsidion
confidence: high
sources: []
related: [[[vault-context-loading]]]
---
# Example Note Title
Content goes here with [[wikilinks]] to related notes...
Rules
- Filenames: kebab-case, 3-5 words
- No orphan notes — at least one [[wikilink]]
- Search before create — no duplicates
- Tags: short, single-word preferred
Note Types
pattern
debugging
research
project
daily
tool
language
framework
Subfolder Rule
When 3+ notes share a common prefix, move them into a named subfolder. One level only — never nest subfolders.
Session Lifecycle: Complete Data Flow
How knowledge flows through a full Claude Code session
1
SessionStart — Hook reads vault, injects project notes + recent notes as context
2
Session Active — Claude works with vault knowledge available in context window
3
PreCompact — If context fills up, snapshot current task + active files to daily note
4
Session Continues — Work resumes with compacted context + vault snapshot
5
SubagentStop — Async hook captures subagent transcripts as they finish (parallel)
6
SessionEnd — Analyze transcript, detect learnings, append to daily note
7
Queue — Significant sessions/subagents queued to pending_summaries.jsonl
8
Summarize — Background process generates structured notes via the CLI AI backend
9
Next Session — New notes are available for context injection on next start
A self-reinforcing loop: each session's learnings feed the next session's context
Configuration: config.yaml
Centralized settings with precedence: defaults → config.yaml → CLI args
session_start_hook:
ai_model: null # Model for AI note selection
max_chars: 4000 # Max context injection characters
ai_timeout: 25 # AI call timeout in seconds
recent_days: 3 # Days to look back for recent notes
debug: false # Append injected context to debug log
use_embeddings: true # Blend semantic matches into context
session_stop_hook:
ai_model: null # Model for AI classification
ai_timeout: 25 # AI call timeout in seconds
auto_summarize: true # Auto-launch summarizer
subagent_stop_hook:
enabled: true # Enable subagent capture
min_messages: 3 # Minimum messages to be worth capturing
excluded_agents: "vault-explorer,research-agent"
pre_compact_hook:
lines: 200 # Transcript lines to analyse
summarizer:
model: claude-sonnet-4-6
max_parallel: 5 # Concurrent summarization tasks
transcript_tail_lines: 400
max_cleaned_chars: 12000
persist: false # SDK session persistence
embeddings:
model: BAAI/bge-base-en-v1.5 # ~134MB ONNX, MRR 0.889
min_score: 0.35 # Cosine similarity threshold
top_k: 10 # Default result count
git:
auto_commit: true # Auto-commit after vault writes
Parsed by vault_common.load_config() — stdlib-only YAML parser, one level of nesting, inline comments supported.
Research Agent: External Knowledge Capture
A Sonnet-powered agent that searches, synthesizes, and saves
User Request
→
vault-explorer
→
Web Search
→
Always Save to Vault
→
Reindex
Workflow
1
Dispatch vault-explorer agent to check for existing knowledge
2
Brave Search for web research (mcpl fallback if rate-limited)
3
agentchrome page html → html-to-md for clean markdown (curl fallback)
4
Always save vault note with frontmatter; also save project doc if requested
5
Run update_index.py to rebuild CLAUDE.md
Output
Vault notes always saved with:
- Complete YAML frontmatter
- Source URLs and citations
- Wikilinks to related vault notes
- Confidence levels from research
Project docs (if requested):
- Style-guide compliant, no frontmatter
- Saved alongside the vault note
Sonnet-powered
vault-explorer first
dual-save
Vault Explorer Agent: Read-Only Vault Search
A Haiku-powered subagent that isolates vault lookups from the main session
Main Session
→
vault-explorer
→
vault_search.py
|
vault-search (--flag)
→
Priority Folders
→
## Answer
7-Step Search Procedure
1
Semantic: vault_search.py --json; ≥3 results → skip to step 6
2
Metadata: vault-search --flag with inferred filters; ≥3 results → skip to step 6
3
Orient via ~/ClaudeVault/CLAUDE.md index
4
Extract key signal from query
5
Search by priority folder (query-type table)
6
Rank top 5 by semantic score → folder → signal frequency
7
Synthesize & return fixed two-section format
Folder Priority by Query Type
Error / exception → Debugging/ → Frameworks/ → Languages/
Feature / pattern → Patterns/ → Frameworks/ → Projects/
Cross-project → Projects/ → Patterns/
Library / tool → Tools/ → Frameworks/
Research → Research/ → all folders
Design constraints:
- Read-only — never writes vault notes
- No
update_index.py calls
- Graceful fallback when embeddings.db absent
- Falls back to
research-agent
Haiku-powered
Isolated context
Read-only
MRR 0.889
note_index
Obsidian Graph View: Visual Knowledge Map (Optional)
Domain-based color groups with priority-ordered matching
Obsidian applies first-match-wins coloring. Since many notes have multiple tags, the priority order ensures consistent grouping. A debugging note tagged with a project name appears Cyan (project), since project membership is the highest-priority grouping.
check_graph_coverage.py audits coverage:
• Finds tags used in vault but not in any color group
• Finds stale color group entries not used in any note
• Supports --threshold N and --json output
Source Repo & Installation
parsidion/ → ~/.claude/ → ~/ClaudeVault/
Source Repository
parsidion/
install.py
CLAUDE-VAULT.md
agents/
research-agent.md
vault-explorer.md
skills/parsidion/
SKILL.md
scripts/
templates/
scripts/
show-context
Install Commands
uv run install.py # interactive
uv run install.py --force --yes # reinstall
uv run install.py --dry-run # preview
uv run install.py --uninstall # remove
Installed To
~/.claude/
settings.json
CLAUDE-VAULT.md
agents/
scripts/
skills/parsidion/
SKILL.md
scripts/
templates/
Git Integration
Optional vault git version control:
cd ~/ClaudeVault && git init
# Scripts auto-commit after writes
# No .git = silent no-ops
Trigger Evaluation: Skill Quality Assurance
Measure how accurately Claude invokes the vault skill
The SKILL.md description determines when Claude Code auto-invokes the vault skill. The trigger eval harness measures precision, recall, and accuracy to ensure the description is optimally tuned.
How It Works
1
Parse name & description from SKILL.md
2
20 test queries (10 should-trigger, 10 should-not)
3
Each query runs 3x for statistical reliability
4
6 parallel workers (ProcessPoolExecutor)
5
Computes precision, recall, accuracy
Key Details
- 60 total API calls per eval run
- 5 real distractor skills included for realism
- Must run from separate terminal
- Results saved to eval_results.json
bash ~/.claude/skills/\
parsidion/scripts/\
run_trigger_eval.sh
What We Built
Core Components
- SessionStart Hook — context injection from vault
- SessionEnd Hook — learning capture & queuing
- SubagentStop Hook — subagent learning capture (async)
- PreCompact Hook — state snapshots
- Summarizer — AI-powered note generation
- vault_common.py — shared stdlib-only library
- update_index.py — auto-generated CLAUDE.md
- Research Agent — vault-first web research
- Vault Explorer Agent — read-only Haiku vault search (7-step)
- Trigger Eval — skill quality measurement
- CLAUDE-VAULT.md — always-on vault-first guidance
- Semantic Search — bge-base embeddings, MRR 0.889, auto-rebuild
- note_index + vault-search (filter mode) — sub-ms metadata search, DB-first find_* functions
Design Principles
- Vault-first — check before debugging or implementing
- Python stdlib only — maximum portability
- Obsidian-compatible — graph view, wikilinks, templates (optional)
- Config-driven — centralized YAML with fallbacks
- Git-integrated — optional auto-commit on writes
- Self-reinforcing — each session feeds the next
- AI-augmented — optional Haiku/Sonnet modes
parsidion • MIT License