Agentbrainsystem

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.

npm install -g agentbrainsystem   # provides the `abs` CLI
abs setup                         # installs hooks + registers the MCP server with Claude Code

Or build from source

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):

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

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 — 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

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

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

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
• Source: victorbjuliani/agentbrainsystem
• License: MIT
• Homepage: https://victorbjuliani.github.io/agentbrainsystem/

Install and usage instructions live in the source repository linked above.