session-brain skill
✓ VerifiedBuilds a searchable topic graph over agent session history using local clustering to map and analyze session trends.
- GitHub stars
- 3,716
- Files
- 1
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the session-brain skill do?
session-brain builds a searchable topic graph over agent session history using local clustering to map and analyze session trends.
Summary generated from the skill's SKILL.md.
About the session-brain skill
Mapping and analyzing trends across your Claude session history is what session-brain enables through local clustering. Developers use this tool to build a searchable topic graph that visualizes how different conversations connect and evolve over time. It operates by running deterministic Python via the obsidian-wiki CLI to process transcripts and generate a sidecar directory at ~/.claude/session-brain/ without ever modifying your existing vault.
An agent should load this skill when it needs to survey broad topics, identify active versus dormant subjects, or find bridge sessions that connect separate conversation clusters. The process involves building the graph with the sessions-build command, naming clusters using top terms and exemplars, and finally presenting a visual map via a browser-viewable HTML file. Users can fine-tune the results using flags like --mutual for tighter clusters, --half-life to adjust recency, or --min-sim to reduce graph density. The output includes insights into momentum, session size, and recency through a specialized visualization tool.
What an agent can do with it
- 1Analyze session trendsIdentify which topics are currently gaining momentum and which have become dormant over recent months.
- 2Organize large session historiesGroup hundreds of sessions into named clusters using top terms and exemplar sessions.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the session-brain skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the session-brain skill in Plugin
/plugin marketplace add Ar9av/obsidian-wiki /plugin install obsidian-wiki@obsidian-wiki
Install the session-brain skill in Claude Code
~/.claude/skills/session-brain/SKILL.md
$ npx degit Ar9av/obsidian-wiki/skills/session-brain ~/.claude/skills/session-brainInstall the session-brain skill in Claude Code (project)
.claude/skills/session-brain/SKILL.md
$ npx degit Ar9av/obsidian-wiki/skills/session-brain .claude/skills/session-brainInstall the session-brain skill in Codex
~/.agents/skills/session-brain/SKILL.md
$ npx degit Ar9av/obsidian-wiki/skills/session-brain ~/.agents/skills/session-brainInstall the session-brain skill in Gemini CLI
~/.gemini/skills/session-brain/SKILL.md
$ npx degit Ar9av/obsidian-wiki/skills/session-brain ~/.gemini/skills/session-brainInstall the session-brain skill in Claude.ai
npx degit Ar9av/obsidian-wiki/skills/session-brain session-brain && zip -r session-brain.zip session-brain # claude.ai → Customize → Skills → + → Create skill → Upload a skill → session-brain.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablear9av/obsidian-wiki/skills/session-brain is public and reachablegithub.com/ar9av/obsidian-wiki/tree/HEAD/skills/session-brai ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/ar9av/obsidian-wiki/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/ar9av/obsidian-wiki/blob/HEAD/skills/session-brai ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/ar9av/obsidian-wiki/blob/HEAD/skills/session-brai ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 95 linesgithub.com/ar9av/obsidian-wiki/blob/HEAD/skills/session-brai ↗Pass
SKILL.md
View on GitHubSession 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,
--fullrebuilds from scratch; nothing is lost.
Files in this skill
1session-brain skill questions
How do I install the session-brain skill in Claude Code?
Run npx degit Ar9av/obsidian-wiki/skills/session-brain ~/.claude/skills/session-brain. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the session-brain skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Does this skill modify my existing vault?
No, it creates a sidecar output in a specific directory and never touches the vault.
How do I name clusters without reading every transcript?
You can name clusters using only the top terms and exemplars provided by the tool, which is designed to take only one turn.
What if the generated graph looks incorrect?
You can perform a full rebuild from scratch using the --full flag.