AgentBrainSystem
victorbjuliani/agentbrainsystem
Memória semântica persistente para agentes de código — local, grátis, sem esquecer
Ver no GitHubMCP server que fornece memória persistente local-first para agentes de IA em sessões de codificação. Captura contexto, decisões e constraints entre sessions e recupera semanticamente o que importa, rodando 100% offline em SQLite embarcado.
Instalação
npx convez-ai victorbjuliani/agentbrainsystem1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter contexto de decisões arquiteturais entre sessões do Claude Code
- Recuperar constraints e regras de negócio aplicadas em código anterior
- Evitar repetição de bugs já resolvidos em bases de código complexas
Veredito

Solução técnica honesta para um problema real de agentes de IA — perda de contexto entre sessões. Implementação compacta (8 dependências), bem testada (807 testes), genuinamente local-first. Mais adequado para desenvolvedores que trabalham com Claude Code em projetos que exigem memória de constraints críticas.
README
A tradução para o português deste README ainda está na fila.
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
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 <id> for any other
supported harness (see Connect). 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 theexportlines 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 <id> 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 <id> 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 <slug>
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 <id> # move an existing memory into the global brain
abs promote <id> --as "…" # curate-copy: file exactly "…" globally, keep the original in its project
abs export <path> # write the whole store to a portable artifact
abs import <path> # 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 <id>] # 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
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.
$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.
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 <id>
to wire one (no flag = Claude Code). The same local memory store is shared across all of them.
Fully — MIT licensed. Star it, fork it, read every line.
Contributing & docs
- 🤝 Contributing:
CONTRIBUTING.md— setup, validation, workflow - 🌐 Website: https://victorbjuliani.github.io/agentbrainsystem/
- 📖 Agent & contributor onboarding:
docs/agent-handbook.md - 🏗️ Design decisions:
docs/adr/ - 🗺️ Roadmap & requirements: GitHub Issues
License
MIT © 2026 Victor B. Juliani