session-brain

name

session-brain

description

Build and maintain a topic graph over your agent session history. Reads every Claude session transcript plus the pruned sessions that survive only in history.jsonl, clusters them by topic using local TF-IDF (no API calls, no embeddings), and writes an interactive graph you can open in a browser. Use when the user says "/session-brain", "build my session map", "cluster my claude sessions", "map my session history", "rebuild the session graph", "show me my session graph", "what have I been working on lately", "what topics have gone stale". Different from wiki-history-ingest, which distils sessions into vault pages: this builds a retrieval index over the raw sessions and never writes to the vault.

Session Brain

Builds a searchable topic graph over your agent session history. The output is a sidecar at ~/.claude/session-brain/ — the vault is never touched.

All the heavy lifting is deterministic Python in the obsidian-wiki CLI. Your only job is to name the clusters, which takes exactly one turn and requires reading no transcripts.

When to use which skill

Goal	Skill
Build or refresh the graph; survey topics	session-brain (this one)
Find and load a specific past session	session-search
Distil sessions into permanent vault pages	wiki-history-ingest / claude-history-ingest

Step 1: Build

obsidian-wiki sessions-build --json

Roughly 3 seconds cold on ~1000 sessions, well under a second incrementally — it re-reads only transcripts whose size or mtime changed. Useful flags:

Flag	When
--full	Ignore all caches and re-read everything
--mutual	Tighter, smaller clusters (mutual-kNN edges only)
--half-life N	Change the recency half-life (default 90 days)
--min-sim 0.15	Fewer, stronger edges — use if the graph is too dense to read
--skip name	Exclude a project. Match is substring-based; pass the bare name, because cache dirs start with - and argparse reads that as a flag

Report the headline numbers: total sessions, how many have transcripts vs. are history-only, edges, and cluster count.

Step 2: Name the unnamed clusters

obsidian-wiki sessions-clusters --unnamed --json

Each cluster comes with top_terms and exemplars (its three highest-degree sessions, whose titles are already in graph.json). That is all you need. Do not open transcripts to name a cluster — the whole design goal is that naming costs one turn regardless of corpus size.

Write a 3–5 word name and a one-sentence summary per cluster, then:

obsidian-wiki sessions-name --from - <<'EOF'
[{"id": 3, "name": "warden telemetry pipeline", "summary": "Building and debugging the redacted telemetry chain."}]
EOF

Names are stored in names.json keyed by the cluster's dominant vocabulary, not its id — so they survive rebuilds even though cluster ids are positional and shift as the corpus grows. On repeat runs --unnamed is usually empty and this step is free.

If a cluster's terms are genuinely incoherent, name it honestly ("mixed — short sessions") rather than inventing a theme.

Step 3: Report the map

Read clusters.json and tell the user:

• Biggest topics — by size
• What's hot — highest momentum (activity in the last 30 days vs. the 60 before it)
• What's gone quiet — dormant: true (low recency and nothing in 60 days)
• Where topics meet — bridges, the sessions that connect two otherwise separate topics. These are often the most interesting sessions in the graph.

Then offer the visualisation:

open ~/.claude/session-brain/graph.html

Node size is session length, brightness is recency, hollow rings are history-only sessions, and gold borders are bookmarked ones. The time slider and search box filter together.

Notes

• Never write to the vault from this skill. If the user wants session knowledge in the vault, that is wiki-history-ingest.
• History-only sessions are real. Roughly 40% of a long-lived cache exists only as prompts in history.jsonl; those get graph nodes and are findable, but can never be loaded. Say so plainly rather than implying they are missing.
• The graph is derived data. If it looks wrong, --full rebuilds from scratch; nothing is lost.