# Agentbrainsystem > Local-first persistent memory for AI coding agents (Claude Code/MCP). Reliable semantic recall — $0, offline, open source. - **Type:** MCP server - **Install:** `agentstack add mcp-victorbjuliani-agentbrainsystem` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [victorbjuliani](https://agentstack.voostack.com/s/victorbjuliani) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [victorbjuliani](https://github.com/victorbjuliani) - **Source:** https://github.com/victorbjuliani/agentbrainsystem - **Website:** https://victorbjuliani.github.io/agentbrainsystem/ ## Install ```sh agentstack add mcp-victorbjuliani-agentbrainsystem ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Persistent memory for AI coding agents — local-first, $0, and it actually recalls. Your agent forgets everything between sessions. agentbrainsystem captures every coding session — across five harnesses — and recalls what matters next time, 100% on your machine. No cloud, no account, no API keys required. Why · Install · How it works · What's different · Benchmarks · Connect · Graph UI · FAQ --- ## Why Every new session, your agent starts from zero. The decision you locked in yesterday? Gone. The bug you already solved? It'll solve it again — differently, worse. So you copy-paste context and re-explain the same constraints, every day. **That's a job no human should have.** Existing agent-memory tools capture data but often fail at the part that matters: **recall that returns the right thing**. agentbrainsystem is a deliberately small, owned alternative that does a few things well — and runs entirely on your machine. ## Install Requires **Node ≥ 22**. ```bash npm install -g agentbrainsystem # provides the `abs` CLI abs setup # installs hooks + registers the MCP server with Claude Code ``` Or build from source ```bash git clone https://github.com/victorbjuliani/agentbrainsystem.git cd agentbrainsystem npm install && npm run build # provides the `abs` CLI abs setup ``` `abs setup` is the one-shot onboarding: it installs the memory hooks **and** registers the MCP server with your harness (idempotent; if the harness CLI isn't found it just prints the manual command). With no flag it targets **Claude Code**; pass `--harness ` for any other supported harness (see [Connect](#connect-your-harness)). It then offers a **guided, optional LLM step** (local Ollama leads — $0/offline, no key; a hosted OpenAI-compatible endpoint second; or skip) so abs can distil your sessions into sharper recall — your API key is never stored, setup just prints the `export` lines. The step is **skipped automatically** in non-interactive/CI/`--harness` runs (no prompt, exit 0). Restart the harness afterwards and recall/remember are automatic. The first embedding call downloads the local model (~one-time, ~35 s); after that it runs **offline**. Everything is local by default — `$0`, no network. The store lives at `~/.agentbrainsystem/memory.db` and is never committed. ## How it works Three steps, zero effort once installed: | Step | What happens | | |---|---|---| | **1 · Capture** | Hooks (or, for OpenCode, an in-process plugin) auto-ingest every session when it settles. | `$0 · no LLM` | | **2 · Store** | Local embeddings in an embedded SQLite + `sqlite-vec` + FTS5 store, on your machine. | `offline` | | **3 · Recall** | Hybrid semantic + keyword search surfaces relevant memory — at session start **and on every prompt**. | `per-prompt · MCP` | **Distillation is automatic by default once you configure an LLM.** When a substantial session ends, a background cadence distills it into durable lessons and promotes them to the project's auto-memory (loaded into Claude Code's native context) — **no manual step**. It never touches your git-tracked `CLAUDE.md` (decisions wait for a manual `abs optimize`), runs detached so it never blocks session close, and announces itself once with its per-session cost. Opt out any time with `ABS_AUTO_DISTILL=0`. ## What makes it different Not another write-only memory bucket. The parts most tools skip: - 🎯 **Recall that returns the right thing — every prompt.** Hybrid semantic + keyword search, injected on **every turn**, not just dumped once at session start. Durable **lessons and decisions are ranked above raw chatter**, so signal beats noise — the decision you locked in last week surfaces exactly when you're about to break it. - 🩹 **Verifiable, self-healing memory — no external tooling.** Every fact your agent edits is anchored to real code (`file:line@commit`) by abs's **own** embedded tree-sitter index — symbol-level for TS/JS/Python, file-level for everything else. Recall labels each fact **✓verified / ~claimed / ⚠stale** against your *live* code; anchors **re-follow code when it moves** and go **stale** when it's deleted — in any git repo, offline, zero setup. A PreToolUse guard fires **in the loop**, before an edit lands: it flags code you're about to duplicate and surfaces past memory about the file you're touching. - 🔒 **Local-first, $0, offline — for real.** No cloud, no account, no API keys required, no telemetry. Local embeddings by default; an LLM that sharpens recall is **optional but recommended** — a guided, skippable step in `abs setup` (local Ollama needs no key and stays $0/offline; a hosted OpenAI-compatible endpoint also works). The API key is never stored — setup just prints the `export` lines for you. - 🗂️ **Project-scoped by default.** Recall is isolated per project — project B's memory never bleeds into project A. Promote a lesson to the global brain when it's worth sharing everywhere. - 🪶 **Deliberately small.** 8 runtime dependencies (two are the embedded WASM tree-sitter parser), embedded SQLite, no server to run. ~18k lines of production code you can actually read (plus ~15k of tests). - 🪼 **Your memory, as a living creature.** A localhost UI renders the whole store as one bioluminescent jellyfish whose anatomy *is* the memory — dome = consolidated core, tentacles = sessions, beads = observations (`abs ui`). - 🎒 **Portable, no lock-in.** Export/import the whole store as a single file. ## Benchmarks Measured on Apple Silicon (M-series), Node 26, over a synthetic 5,000-observation store. **Reproduce with `npm run bench`** — no network, no external services. | Metric | Result | |---|---| | Per-prompt FTS recall (hot path) | **p50 ~4.4 ms** (median per-prompt latency) | | Semantic embed — warm (steady-state) | **~2–5 ms** (first call ~400 ms, model load) | | Ingest throughput | **~4,500 observations/sec** | | On-disk footprint | **~616 bytes/observation** (5k obs ≈ 2.9 MB) | | Runtime dependencies | **8** · embedded SQLite · 0 servers | > We benchmark on our own axis — latency, footprint, and minimalism — and publish only what's > measured and reproducible. We don't chase a retrieval-accuracy headline number on someone else's > dataset; if we ever publish one, it'll be on a public benchmark with the script in this repo. ## Connect your harness Memory spans **five harnesses**, each wired the same way — `abs install-hooks` (the lifecycle wiring) + `abs setup` (hooks + MCP registration). With **no flag** both target the detected default (Claude Code); pass `--harness ` to target another: | Harness | `--harness` id | One-shot | |---|---|---| | Claude Code | `claude-code` *(default, no flag needed)* | `abs setup` | | Codex CLI | `codex` | `abs setup --harness codex` | | Gemini CLI | `gemini` | `abs setup --harness gemini` | | GitHub Copilot CLI | `copilot` | `abs setup --harness copilot` | | OpenCode | `opencode` | `abs setup --harness opencode` | `abs status` lists which harnesses are installed on this machine (and whether each qualifies for full parity), so you know which `--harness ` to run. To register the MCP server manually, or to wire a second machine (Claude Code shown): ```bash claude mcp add agentbrainsystem -- node /absolute/path/to/agentbrainsystem/dist/cli/cli.js start ``` The 9 MCP tools exposed to the agent: `recall`, `remember`, `memory_status`, `optimize`/`apply` (gated `CLAUDE.md` edits), `forget_preview`/`forget` (two-phase selective hard-delete), `set_session_project`, and `promote` (move — or, with `as`, curate-copy — a memory into the cross-project global brain). The same memory store is shared across every harness. ## Memory creature UI ```bash abs ui # serves the creature at http://127.0.0.1:7717 ``` The store renders as a single **bioluminescent jellyfish** whose anatomy encodes the memory (WebGL2 + HDR bloom): the **dome** is the consolidated core with a neural mesh of similarity, each **tentacle** is a session, each **bead** of light is an observation (colored by kind), brightness is recency, and the most-recent observations pulse. Dark by default (the creature glows); a light theme turns it into a translucent pastel gel. Zoom/orbit freely, inspect, search, and prune memories right from the canvas. Binds to localhost only and ships self-contained (works offline). Falls back to an on-brand message where WebGL2 is unavailable. ### Tray companion (optional) A native **tray companion** (`src-tauri/`, Tauri 2 — macOS / Windows / Linux) keeps the creature glanceable from the menu bar: it reads counts read-only straight from the store (no Node process to sit idle), pulses when the agent learns, and a popover opens the full "ocean" window on demand. **Download** the latest installers (`.dmg` / `.exe` / `.msi` / `.deb` / `.rpm` / `.AppImage`) from the **[Releases page](https://github.com/victorbjuliani/agentbrainsystem/releases/latest)** — macOS apps are unsigned, so the first launch is **right-click → Open**. Installers are built by the tag-triggered `release.yml` (intentionally **not** part of the per-PR CI); build it yourself with `cargo tauri build` (or `dev`) inside `src-tauri/`. ## CLI ```bash abs setup # one-shot onboarding: install hooks + register the MCP server abs uninstall [--purge] # reverse of setup: remove hooks + unregister MCP (--purge wipes the store) abs start # run the MCP server (what Claude Code spawns) abs ingest [...] # opt-in historical ingest — preview default; --apply + --all|--project abs status # db path, schema, counts, index staleness abs doctor # health check (integrity, drift, Claude Code hook wiring) + best-effort update check abs project [...] # set/confirm/skip the current session's project abs remember "…" --global # add a memory to the cross-project global brain abs promote # move an existing memory into the global brain abs promote --as "…" # curate-copy: file exactly "…" globally, keep the original in its project abs export # write the whole store to a portable artifact abs import # load an artifact (merge | replace) abs ui [--port N] # serve the interactive memory graph abs consolidate [...] # distill a session into durable lessons (opt-in, needs an LLM) abs optimize [...] # turn distilled memory into gated CLAUDE.md / auto-memory edits (curated; index-visible in MEMORY.md) abs maintain --auto # internal auto-distill cadence (consolidate → auto-memory); runs detached after SessionEnd abs forget [...] # selectively hard-delete memories — IRREVERSIBLE, export first abs install-hooks [--harness ] # register the memory hooks for a harness (idempotent, backup-first) ``` ## Updating ```bash npm install -g agentbrainsystem@latest # pull the new CLI abs setup # idempotent — reconciles hooks + MCP registration ``` `abs setup` is safe to re-run: it only adds/updates the hooks and MCP entry, never duplicates them. Re-running after an upgrade also picks up any change to the hook or MCP wiring a new version introduces. `abs doctor` does a single, best-effort GET to the public npm registry to tell you when a newer version is published. It sends **no** data about you or your machine, runs **only** from that explicit command (never the hooks or recall path), and silently skips the check when you're offline — so the local-first, no-telemetry guarantee is unaffected. ## Configuration | Env | Default | Purpose | | --- | --- | --- | | `ABS_DB_PATH` / `ABS_HOME` | `~/.agentbrainsystem/memory.db` | where the store lives | | `ABS_EMBED_PROVIDER` | `local` | `local` \| `gemini` \| `voyage` | | `ABS_RECALL_SCOPE` | `project` | recall isolation: `project` \| `global` | | `ABS_GUARD_MODE` | `warn` | PreToolUse guard: `warn` \| `block` | | `ABS_LLM_BASE_URL` / `ABS_LLM_MODEL` | _(unset → consolidation off)_ | OpenAI-compatible endpoint for `abs consolidate` | | `ABS_AUTO_DISTILL` | `on` | auto-distill cadence after SessionEnd (needs an LLM): `on` \| `off`. `0` opts out | | `DISTILL_MIN_OBS` | `25` | min observations in a just-ended session for it to be cadence-due | | `ABS_SELF_HEAL_HOOKS` | `on` | re-assert evicted Claude Code hooks on MCP launch (`abs start`); `0` opts out | Out of scope (for now): multi-user/team sharing, image/vision embeddings, heavyweight consolidation tiers. ## FAQ Does it send my code anywhere? No, not by default — everything runs locally and offline, no telemetry, no account. The one exception is the optional LLM you connect during `abs setup`: that is the single outbound call, and only if you opt in. A **local Ollama** stays entirely on your machine (still $0/offline); skip the step and there are no network calls at all. Does it cost anything? $0 by default — local embeddings, no API keys required. An LLM for deeper consolidation is an **optional, skippable step** in `abs setup` (a **local Ollama** is $0 too); a hosted OpenAI-compatible endpoint is the only paid option, and only if you choose it. Skip the step and it stays off. Which agents does it work with? Five harnesses: **Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, and OpenCode** — each via MCP, with hands-free session capture and context injection through that harness's native lifecycle (shell hooks for four; an in-process plugin for OpenCode). Run `abs setup --harness ` to wire one (no flag = Claude Code). The same local memory store is shared across all of them. Is it open source? Fully — MIT licensed. Star it, fork it, read every line. ## Contributing & docs - 🤝 **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, validation, workflow - 🌐 **Website:** https://victorbjuliani.github.io/agentbrainsystem/ - 📖 **Agent & contributor onboarding:** [`docs/agent-handbook.md`](docs/agent-handbook.md) - 🏗️ **Design decisions:** [`docs/adr/`](docs/adr/) - 🗺️ **Roadmap & requirements:** [GitHub Issues](https://github.com/victorbjuliani/agentbrainsystem/issues) ## License [MIT](LICENSE) © 2026 Victor B. Juliani ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [victorbjuliani](https://github.com/victorbjuliani) - **Source:** [victorbjuliani/agentbrainsystem](https://github.com/victorbjuliani/agentbrainsystem) - **License:** MIT - **Homepage:** https://victorbjuliani.github.io/agentbrainsystem/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-victorbjuliani-agentbrainsystem - Seller: https://agentstack.voostack.com/s/victorbjuliani - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.