superbrain
installs/mo · npmstarsforks
How to install superbrain?
m3talux/superbrain
$git clone https://github.com/m3talux/superbrainSession memory for Claude Code. Auto-captures every session into a plain Obsidian markdown vault. Zero config. MIT. macOS + Linux.
README.md
| 1 | <div align="center"> |
| 2 | |
| 3 | # 🧠 SuperBrain |
| 4 | |
| 5 | **Session memory for Claude Code — a second brain that builds itself.** |
| 6 | |
| 7 | Every Claude Code session — across every project, on every machine — is captured into a plain Obsidian markdown vault you fully own. Zero config, no LLM of its own, no cloud. SuperBrain observes the sessions you're already running and writes the journal you never have time to. |
| 8 | |
| 9 | [](LICENSE) |
| 10 | [](package.json) |
| 11 | [](https://github.com/m3talux/superbrain/actions/workflows/ci.yml) |
| 12 | [](#vault-structure) |
| 13 | [](https://obsidian.md) |
| 14 | |
| 15 | </div> |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | > **Status:** in active development. Interfaces and behavior may change before a tagged release. |
| 20 | |
| 21 | ## Why |
| 22 | |
| 23 | 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: |
| 24 | |
| 25 | - **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. |
| 26 | - **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. |
| 27 | |
| 28 | **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. |
| 29 | |
| 30 | 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. |
| 31 | |
| 32 | ## Quick start |
| 33 | |
| 34 | ```text |
| 35 | # In Claude Code: |
| 36 | /plugin marketplace add m3talux/superbrain |
| 37 | /plugin install superbrain |
| 38 | ``` |
| 39 | |
| 40 | That's it. On the **first session** the plugin runs a one-time setup (installs its |
| 41 | search dependencies in the background) and tells you it's doing so; capture is |
| 42 | fully active from the next session. SuperBrain writes to its own vault at |
| 43 | `~/.superbrain/vault` — a fixed, predictable location with no environment |
| 44 | variables to set. Point Obsidian at that folder and you're done. |
| 45 | |
| 46 | If you already have an Obsidian vault you want to bring along, see |
| 47 | [Vault setup](#vault-setup) below — `/superbrain:migrate` is the preferred path. |
| 48 | |
| 49 | Installed at **user scope**, the plugin's hooks register for *every* project automatically — there is nothing else to do, ever. |
| 50 | |
| 51 | > If SuperBrain saves you context, please star ⭐ — it's the only signal we have. |
| 52 | |
| 53 | ## Supported platforms |
| 54 | |
| 55 | - **macOS** — Apple Silicon + Intel. CI-tested. |
| 56 | - **Linux** — Ubuntu 22.04+ verified; other distros likely fine. CI-tested. |
| 57 | - **Windows** — native Windows support is in progress: the cross-platform |
| 58 | spawn wrapper, path-separator handling, and platform-aware bootstrap hints |
| 59 | are in place, but the test suite is not yet fully Windows-portable and |
| 60 | Windows isn't on the CI matrix. See |
| 61 | [Install troubleshooting](#install-troubleshooting) for the first-install |
| 62 | failure modes and the fixes. |
| 63 | |
| 64 | Tested on Node 20 LTS and Node 22. |
| 65 | |
| 66 | ## How it works |
| 67 | |
| 68 | ```mermaid |
| 69 | flowchart LR |
| 70 | A[Tool use / prompt] -->|PostToolUse, UserPromptSubmit<br/>async, no LLM| B[NDJSON log<br/>+ salient markers] |
| 71 | B --> C{Checkpoint?<br/>PreCompact / SessionEnd /<br/>Stop if pending} |
| 72 | C -->|detached, lock-serialized| D[sb-distill<br/>claude -p] |
| 73 | D --> E[Router] |
| 74 | E --> F[(Obsidian vault<br/>notes only)] |
| 75 | D -.->|incremental rebuild| I[Daily note for today] |
| 76 | I --> F |
| 77 | C -.->|byte cursor| B |
| 78 | ``` |
| 79 | |
| 80 | 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. |
| 81 | 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. |
| 82 | 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. |
| 83 | 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. |
| 84 | |
| 85 | ## Features |
| 86 | |
| 87 | **Capture** |
| 88 | |
| 89 | - ✅ Globally installed, zero per-project setup, **no API key** (reuses your Claude Code auth) |
| 90 | - ✅ **One-shot project discovery** on first |
People who liked this also viewed
6 picksType
- excel-mcpA Model Context Protocol (MCP) server for working with Excel (.xlsx) files without requiring Microsoft Excel. Enables AI assistants to create, read, modify, and format spreadsheets using openpyxl, fully in Python and cross-platform.MCP ServersOct 2025
- memories-with-lessons-mcp-serverI enhance the existing memory mcp server from the official mcp github, so big thanks and credits for creating thisMCP ServersFeb 2025
- anytype-mcpAn MCP server enabling AI assistants to interact with Anytype - your encrypted, local and collaborative wiki - to organize objects, lists, and more through natural language.MCP ServersJul 2026
- mcp-server-kubernetesMCP Server for kubernetes management commandsMCP ServersJul 2026
- thoughtboxThoughtbox is an intention ledger for agents. Evaluate AI's decisions against its decision-making.MCP ServersJul 2026
- google-drive-mcpA Model Context Protocol (MCP) server that provides secure integration with Google Drive, Docs, Sheets, Slides and Calendar. It allows Claude Desktop and other MCP clients to manage files in Google Drive through a standardized interface.MCP ServersJul 2026
