superbrain

Status: in active development. Interfaces and behavior may change before a tagged release.

Why

Every Claude Code session ends and the reasoning vanishes. Decisions, trade-offs, the "we tried X and it didn't work" history — gone with the terminal scrollback. CLAUDE.md fixes the rules; SuperBrain fixes the journal. The Claude Code memory ecosystem has split in two, and neither half is what you actually want:

• Automatic but opaque (claude-mem, mcp-memory-service): great zero-config capture, but it lives in a SQLite/Chroma blob you can't browse, edit, or own.
• Obsidian but manual (basic-memory, claudesidian, obsidian-second-brain): a beautiful markdown vault, but you have to remember to run commands or hope the model decides to call a tool.

No mature tool does all of: globally installed → automatic capture → into a plain Obsidian vault → with incremental daily notes → that you fully own and can git-sync. SuperBrain is that missing bridge.

This isn't vibes: ~23 prior-art projects and the current Claude Code platform were surveyed, and every architectural decision was challenged before a line was written.

Quick start

# In Claude Code:
/plugin marketplace add m3talux/superbrain
/plugin install superbrain

That's it. On the first session the plugin runs a one-time setup (installs its search dependencies in the background) and tells you it's doing so; capture is fully active from the next session. SuperBrain writes to its own vault at ~/.superbrain/vault — a fixed, predictable location with no environment variables to set. Point Obsidian at that folder and you're done.

If you already have an Obsidian vault you want to bring along, see Vault setup below — /superbrain:migrate is the preferred path.

Installed at user scope, the plugin's hooks register for every project automatically — there is nothing else to do, ever.

If SuperBrain saves you context, please star ⭐ — it's the only signal we have.

Supported platforms

• macOS — Apple Silicon + Intel. CI-tested.
• Linux — Ubuntu 22.04+ verified; other distros likely fine. CI-tested.
• Windows — native Windows support is in progress: the cross-platform spawn wrapper, path-separator handling, and platform-aware bootstrap hints are in place, but the test suite is not yet fully Windows-portable and Windows isn't on the CI matrix. See Install troubleshooting for the first-install failure modes and the fixes.

Tested on Node 20 LTS and Node 22.

How it works

flowchart LR
  A[Tool use / prompt] -->|PostToolUse, UserPromptSubmit<br/>async, no LLM| B[NDJSON log<br/>+ salient markers]
  B --> C{Checkpoint?<br/>PreCompact / SessionEnd /<br/>Stop if pending}
  C -->|detached, lock-serialized| D[sb-distill<br/>claude -p]
  D --> E[Router]
  E --> F[(Obsidian vault<br/>notes only)]
  D -.->|incremental rebuild| I[Daily note for today]
  I --> F
  C -.->|byte cursor| B

1. Observe — PostToolUse / UserPromptSubmit hooks append a compact event line to a per-session NDJSON log. No LLM on this path, so it can never rate-limit, stall, or disrupt your turn.
2. Pin salience — a deterministic scorer drops a structured marker into the log at the moments that matter (a commit, a file-churn spike, a context switch), so the later summary is anchored to what happened instead of re-derived from noise.
3. Distill at checkpoints — at PreCompact, SessionEnd, or a pending-gated Stop, one detached, lock-serialized claude -p reads the delta since a byte-offset cursor, classifies it, and writes routed notes via an in-process vault writer.
4. Update the day's journal — each distill incrementally rebuilds today's daily/<date>.md from the per-session state (digest line + routed-note links + threads). Deterministic concat, no extra LLM call.

Features

Capture