claude-code — parsidion
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
Parsidion Architecture
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

modelclaude-sonnet-4-6
max_parallel5
tail_lines400
max_chars12000
persistfalse
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/ — graph.json colors
  config.yaml — user settings
  CLAUDE.md — auto-generated index
  pending_summaries.jsonl
  Daily/YYYY-MM/DD.md — session logs (e.g. Daily/2026-03/13.md)
  Projects/ — per-project context
  Languages/ — Python, Rust, TS...
  Frameworks/ — FastAPI, Next.js...
  Patterns/ — design patterns
  Debugging/ — error fixes
  Tools/ — CLI & packages
  Research/ — deep-dive topics
  History/ — historical notes
  Templates/ → symlink to skill 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
Projects
Priority 1
Debugging
Priority 2
Patterns
Priority 3
Research
Priority 4
Tools & SDKs
Priority 5
Languages
Priority 6
Terminal
Priority 7
Graphics / 3D
Priority 8
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 (always-on guidance)
  agents/
    research-agent.md
    vault-explorer.md (Haiku, read-only)
  skills/parsidion/
    SKILL.md
    scripts/ (11 Python scripts + html-to-md.py)
    templates/ (8 templates + config)
  scripts/
    show-context (context preview)

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 — hook registrations
  CLAUDE-VAULT.md — @imported by CLAUDE.md
  agents/
  scripts/ — show-context only
  skills/parsidion/
    SKILL.md
    scripts/ — incl. html-to-md.py
    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