{"id":50563154,"url":"https://github.com/m3talux/superbrain","last_synced_at":"2026-06-04T12:30:46.621Z","repository":{"id":358890823,"uuid":"1243402539","full_name":"m3talux/superbrain","owner":"m3talux","description":"Session memory for Claude Code. Auto-captures every session into a plain Obsidian markdown vault. Zero config. MIT. macOS + Linux.","archived":false,"fork":false,"pushed_at":"2026-05-27T13:22:05.000Z","size":645,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T15:17:22.564Z","etag":null,"topics":["agent-memory","ai-memory","anthropic","claude","claude-code","claude-code-plugin","developer-tools","knowledge-management","llm","llm-memory","markdown","mcp","model-context-protocol","note-taking","obsidian","obsidian-md","obsidian-plugin","personal-knowledge-management","pkm","second-brain"],"latest_commit_sha":null,"homepage":"https://alexandrekhoury.com/writing/superbrain-session-memory-claude-code","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m3talux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T10:01:35.000Z","updated_at":"2026-05-27T13:19:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/m3talux/superbrain","commit_stats":null,"previous_names":["m3talux/superbrain"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/m3talux/superbrain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3talux%2Fsuperbrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3talux%2Fsuperbrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3talux%2Fsuperbrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3talux%2Fsuperbrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m3talux","download_url":"https://codeload.github.com/m3talux/superbrain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m3talux%2Fsuperbrain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33905358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-memory","anthropic","claude","claude-code","claude-code-plugin","developer-tools","knowledge-management","llm","llm-memory","markdown","mcp","model-context-protocol","note-taking","obsidian","obsidian-md","obsidian-plugin","personal-knowledge-management","pkm","second-brain"],"created_at":"2026-06-04T12:30:46.549Z","updated_at":"2026-06-04T12:30:46.613Z","avatar_url":"https://github.com/m3talux.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🧠 SuperBrain\n\n**Session memory for Claude Code — a second brain that builds itself.**\n\nEvery 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.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A520-black.svg)](package.json)\n[![CI](https://github.com/m3talux/superbrain/actions/workflows/ci.yml/badge.svg)](https://github.com/m3talux/superbrain/actions/workflows/ci.yml)\n[![Storage](https://img.shields.io/badge/storage-plain%20Obsidian%20markdown-blueviolet.svg)](#vault-structure)\n[![Works with Obsidian](https://img.shields.io/badge/works%20with-Obsidian-7c3aed.svg)](https://obsidian.md)\n\n\u003c/div\u003e\n\n---\n\n\u003e **Status:** in active development. Interfaces and behavior may change before a tagged release.\n\n## Why\n\nEvery 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:\n\n- **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.\n- **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.\n\n**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.\n\nThis 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.\n\n## Quick start\n\n```text\n# In Claude Code:\n/plugin marketplace add m3talux/superbrain\n/plugin install superbrain\n```\n\nThat's it. On the **first session** the plugin runs a one-time setup (installs its\nsearch dependencies in the background) and tells you it's doing so; capture is\nfully active from the next session. SuperBrain writes to its own vault at\n`~/.superbrain/vault` — a fixed, predictable location with no environment\nvariables to set. Point Obsidian at that folder and you're done.\n\nIf you already have an Obsidian vault you want to bring along, see\n[Vault setup](#vault-setup) below — `/superbrain:migrate` is the preferred path.\n\nInstalled at **user scope**, the plugin's hooks register for *every* project automatically — there is nothing else to do, ever.\n\n\u003e If SuperBrain saves you context, please star ⭐ — it's the only signal we have.\n\n## Supported platforms\n\n- **macOS** — Apple Silicon + Intel. CI-tested.\n- **Linux** — Ubuntu 22.04+ verified; other distros likely fine. CI-tested.\n- **Windows** — native Windows support is in progress: the cross-platform\n  spawn wrapper, path-separator handling, and platform-aware bootstrap hints\n  are in place, but the test suite is not yet fully Windows-portable and\n  Windows isn't on the CI matrix. See\n  [Install troubleshooting](#install-troubleshooting) for the first-install\n  failure modes and the fixes.\n\nTested on Node 20 LTS and Node 22.\n\n## How it works\n\n```mermaid\nflowchart LR\n  A[Tool use / prompt] --\u003e|PostToolUse, UserPromptSubmit\u003cbr/\u003easync, no LLM| B[NDJSON log\u003cbr/\u003e+ salient markers]\n  B --\u003e C{Checkpoint?\u003cbr/\u003ePreCompact / SessionEnd /\u003cbr/\u003eStop if pending}\n  C --\u003e|detached, lock-serialized| D[sb-distill\u003cbr/\u003eclaude -p]\n  D --\u003e E[Router]\n  E --\u003e F[(Obsidian vault\u003cbr/\u003enotes only)]\n  D -.-\u003e|incremental rebuild| I[Daily note for today]\n  I --\u003e F\n  C -.-\u003e|byte cursor| B\n```\n\n1. **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.\n2. **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.\n3. **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.\n4. **Update the day's journal** — each distill incrementally rebuilds today's `daily/\u003cdate\u003e.md` from the per-session state (digest line + routed-note links + threads). Deterministic concat, no extra LLM call.\n\n## Features\n\n**Capture**\n\n- ✅ Globally installed, zero per-project setup, **no API key** (reuses your Claude Code auth)\n- ✅ **One-shot project discovery** on first session in an unknown repo: walks the tree, reads the manifests + CLAUDE.md + README, asks one Sonnet call to produce a substantive `projects/\u003cslug\u003e.md` (stack / architecture / top-level folders / key files / docs / conventions / open questions). Once per project, ever. Never overwrites an existing note.\n- ✅ Automatic capture that does **not** degrade on multi-day sessions\n- ✅ Plain Obsidian markdown — wikilinks, frontmatter, fully `git`-portable, zero lock-in\n- ✅ Smart router: decisions / project facts / people / gotchas / triage capture\n- ✅ Incremental daily notes — rebuilt deterministically from per-session state on every distill, no extra LLM call, no cron, no daemon\n- ✅ Append-or-create, **never** blind-overwrites a note you edited in Obsidian; soft-delete to `.trash/`\n- ✅ Idempotent \u0026 resumable (byte cursor + per-session NDJSON event log); silent failures surface once on next session\n- ✅ One-command migration off a legacy custom scribe (archives, never deletes)\n\n**Search \u0026 recall**\n\n- ✅ Local hybrid search — FTS5 (BM25) + sqlite-vec, fused with Reciprocal Rank Fusion\n- ✅ Tiered autonomous recall: BM25 pointers injected on **every prompt** (no model load, no daemon); a user-visible hybrid brief on session start\n- ✅ **Project-scoped by default**: autonomous recall and the session brief are filtered to the repo you're in, so one project's notes never surface in another (vault-wide deep search stays available via the recall skill and `superbrain_search` MCP)\n- ✅ `superbrain-recall` skill + stdio MCP server (`superbrain_search`) for model-invoked deep search\n- ✅ Incremental index on write + self-healing reconcile on session start (Obsidian-edit / git-pull drift)\n- ✅ All-local embeddings (MiniLM, fetched once \u0026 cached); automatic BM25 fallback — search is never hard-down\n\n**Personalization \u0026 journaling**\n\n- ✅ Daily notes — hybrid digest + linked index, idempotently regenerated per day\n- ✅ Lessons — durable, generalizable rules learned from your pushback\n- ✅ Preferences — a deduplicated profile auto-injected at SessionStart (never edits your `CLAUDE.md`)\n\n**Planned**\n\n- Auto-generated Maps-of-Content (`maps/`) + a lint pass.\n\n## Manual capture with `/superbrain:inject`\n\nAuto-capture handles everything SuperBrain can observe inside a Claude session. When you want to record something it didn't see — a random side thought, a meeting summary from elsewhere, a note imported from another system — use the inject command:\n\n```\n/superbrain:inject I just realized the auth-config endpoint probably needs a TTL field\n/superbrain:inject --from-file ~/Downloads/meeting-summary.md\n/superbrain:inject --project wcloud \"transport is HTTP, not gRPC\"\n```\n\nWhat it does:\n\n- **Short single-blob input** lands verbatim in `capture/`. No LLM call.\n- **Longer or multi-topic input** is split via SuperBrain's inject distiller into the right files: decisions to `decisions/`, project facts to the matching `projects/\u003cslug\u003e.md`, references to people to `people/`, everything else to `capture/`.\n- Today's daily note is updated either way.\n- Every injected note carries `source: inject` provenance so it's trivially auditable.\n\nSafety rails: inject never creates new project notes (use `/superbrain:discover` for that), never reshapes preferences, and never silently loses your input — if the distiller returns nothing, your text is written verbatim to `capture/`.\n\n## Vault structure\n\n```\n~/.superbrain/vault/\n├── projects/      one note per project — status, decisions, current focus\n├── people/        one note per person — role, context, threads\n├── decisions/     atomic, date-prefixed ADR-style notes\n├── daily/         auto-written daily activity\n├── lessons/       durable, generalizable rules learned from your pushback\n├── capture/       raw inbound; triage tag for `/superbrain:inject` items\n├── meta/          preferences.md — deduplicated profile auto-injected at SessionStart\n├── maps/          auto-generated Maps-of-Content   (planned)\n└── index.md       catalog — the primary navigation surface\n```\n\nSystem telemetry (NOT in the vault — lives next to it in `~/.superbrain/`):\n\n```\n~/.superbrain/\n├── sessions/          per-session NDJSON event streams + cursors\n├── transcripts/       full session transcripts (when captured)\n└── index.db           hybrid search index (FTS5 + sqlite-vec)\n```\n\nGenerated files are namespaced (`daily/`, `index.md`) so the auto-rebuilders never touch notes you authored.\n\n## Vault setup\n\nSuperBrain's vault lives at `~/.superbrain/vault` — fixed, predictable, no env vars. Two ways to bring an existing Obsidian vault into the picture:\n\n### Migrate (preferred)\n\n```text\n/superbrain:migrate                  # auto-detects your vault\n/superbrain:migrate ~/Documents/MyVault   # explicit path\n/superbrain:migrate --dry-run        # preview without writing\n```\n\n`/superbrain:migrate` reads your existing Obsidian vault (the source is **never modified**) and copies its content into `~/.superbrain/vault`, fitting it into SuperBrain's structure (`projects/`, `decisions/`, `people/`, `daily/`, etc.). From then on, SuperBrain owns and extends a vault it fully understands — its router, daily notes, and index all behave predictably. **This is the recommended path** for almost every user.\n\n### Adopt (advanced — only when migration isn't an option)\n\n```text\n/superbrain:adopt ~/Documents/MyEstablishedVault\n```\n\n`/superbrain:adopt` does **not** copy anything; it records your existing path as the vault location and starts writing into it directly. Use this only when you have a heavily established Obsidian setup whose structure you do not want to change — broken into folders, plugins, layouts, or conventions SuperBrain isn't designed around.\n\nThe trade-off: SuperBrain will work *on top of* whatever's already there rather than *alongside* a structure it owns. The router may write into folders that don't match your existing convention; auto-generated daily notes will live alongside your hand-authored notes; the search-index reconciler will still self-heal but has more drift to manage. Migration sidesteps all of that.\n\nWhen in doubt: **migrate, don't adopt.**\n\n## Configuration\n\nSuperBrain is configured by command, not by environment. There are no\nrequired env vars. The single optional one:\n\n| Variable | Purpose |\n|---|---|\n| `ANTHROPIC_API_KEY` | Optional escape hatch — distillation uses the Anthropic API instead of your Claude Code subscription. Useful if you want the distill spawns to bypass subscription quota. |\n\n\u003e **Heads-up (2026-06-15):** background `claude -p` / Agent-SDK usage on subscription plans draws from a separate capped monthly credit after this date. If captures stop, SuperBrain surfaces a one-time notice on session start — set `ANTHROPIC_API_KEY` to switch to the API path.\n\n## Syncing your vault\n\nSuperBrain **deliberately does not push your vault anywhere.** It writes plain\nmarkdown into a local folder and nothing leaves the machine. This is a design\nchoice, not a missing feature: a network operation in the capture path could\nhang, stall on an auth prompt, or fail — exactly the failure mode the\n\"never disrupt the session\" guarantee exists to prevent. Backup and\nmulti-machine sync are a solved problem, and dedicated tools do it better and\nsafer than a hook can.\n\nWhat SuperBrain *does* guarantee is that it composes cleanly with whatever sync\nyou choose: writes are append-or-create and idempotent, and the search index\n**self-heals on session start** after the vault changes underneath it (an\nexternal `git pull`, an Obsidian edit, a Syncthing update). So you can layer any\nof the following on top with no special configuration:\n\n- **Adopted an existing Obsidian vault?** If it's already backed by the\n  [Obsidian Git](https://github.com/Vinzent03/obsidian-git) community plugin (or\n  Obsidian Sync), you already have sync — SuperBrain just writes into it and\n  your existing setup ships the changes. Nothing to do.\n- **Using the owned default (`~/.superbrain/vault`)?** Pick one:\n  - Make it a git repo and use **Obsidian Git** for scheduled commit/push.\n  - Point **Syncthing** or a file-sync tool at the folder.\n  - Or a DIY scheduled job — e.g. a `cron` / `launchd` entry running, say every\n    15 minutes:\n\n    ```bash\n    cd ~/.superbrain/vault \u0026\u0026 git add -A \\\n      \u0026\u0026 git commit -q -m \"vault sync $(date -u +%FT%TZ)\" \\\n      \u0026\u0026 git pull --rebase --autostash \u0026\u0026 git push\n    ```\n\nWhichever you choose, treat it as **backup / sync owned by you**, not by the\nplugin. Running the same vault from two machines concurrently can still produce\ngit conflicts in regenerated files (`index.md`, today's `daily/`) — Obsidian\nGit's conflict UX or a single-writer-at-a-time habit avoids that. SuperBrain's\njob is to stay idempotent and drift-tolerant so any of these Just Work; it is\nnot to own your remote.\n\n## Install troubleshooting\n\nSuperBrain runs a one-time `npm ci` + `npm rebuild better-sqlite3` on first session start. If `~/.superbrain/last-failure.txt` reports a bootstrap failure, the message includes a platform-specific hint. Common cases:\n\n- **`npm ci` failed** — network / proxy issue. Retry. If you're behind a corporate proxy, configure `npm config set proxy ...` and retry.\n- **better-sqlite3 native build failed (Windows)** — install [Visual Studio Build Tools](https://github.com/nodejs/node-gyp#on-windows) + Python 3 and retry, or switch to Node 20 LTS which has more prebuilt binaries.\n- **better-sqlite3 native build failed (Linux)** — `sudo apt install build-essential python3` and retry.\n- **better-sqlite3 native build failed (macOS)** — `xcode-select --install` and retry.\n- **better-sqlite3 binding wouldn't load under your Node version** — Node 25's ABI 141 has no published prebuild at the time of writing; downgrade to Node 22 or 20 LTS.\n\nSuperBrain re-tries bootstrap on every session start, so once the underlying issue is fixed, the next session picks it up automatically.\n\n## Design principles\n\nEnforced, tested invariants — not aspirations:\n\n- **Never disrupt the session.** Every hook exits 0 no matter what; `PreCompact` never blocks compaction; a crashing hook is impossible by construction.\n- **Never lose data.** Append-or-create only; a note you edited in Obsidian is never clobbered; deletes go to `.trash/`.\n- **Never silently die.** Failures land in a sentinel surfaced once on the next `SessionStart`.\n- **Idempotent \u0026 self-healing.** Byte cursor + per-session NDJSON event log; a missed or killed run is recovered next session.\n- **No daemon, no scheduler, no API key.** One detached process per checkpoint — nothing to supervise, nothing to leak.\n\n## Development\n\n```bash\nnpm ci\nnpm run typecheck     # tsc --noEmit, zero errors\nnpm run build         # → dist/\nnpm test              # full suite (unit + integration + fresh-clone E2E)\nnpm run release:check # build is reproducible: committed dist/ matches source\n```\n\nContributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Acknowledgements\n\nStanding on the shoulders of: Andrej Karpathy's *LLM Wiki* pattern, [claude-mem](https://github.com/thedotmack/claude-mem) (global-plugin distribution + context injection), [basic-memory](https://github.com/basicmachines-co/basic-memory) (Obsidian-native markdown memory), [obsidian-second-brain](https://github.com/eugeniughelbur/obsidian-second-brain) (AI-first note rules), and [claude-memory-compiler](https://github.com/coleam00/claude-memory-compiler) (session-triggered rollups).\n\n## License\n\n[MIT](LICENSE) © m3talux\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm3talux%2Fsuperbrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm3talux%2Fsuperbrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm3talux%2Fsuperbrain/lists"}