convez.ai
MCP ServerAutomaçãoIntermediário
victorbjuliani

AgentBrainSystem

victorbjuliani/agentbrainsystem

Memória semântica persistente para agentes de código — local, grátis, sem esquecer

Ver no GitHub
BomPluginScore · de 0 a 100

MCP 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/agentbrainsystem

1 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

Estrelas
5
Forks
1
Acompanhando
0
Saúde
85%
Último commit
há 5 meses
Versão
app-v1.2.0
Issues abertas
8
Contribuidores
1

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:

StepWhat happens
1 · CaptureHooks (or, for OpenCode, an in-process plugin) auto-ingest every session when it settles.$0 · no LLM
2 · StoreLocal embeddings in an embedded SQLite + sqlite-vec + FTS5 store, on your machine.offline
3 · RecallHybrid 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.

MetricResult
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 dependencies8 · 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 idOne-shot
Claude Codeclaude-code (default, no flag needed)abs setup
Codex CLIcodexabs setup --harness codex
Gemini CLIgeminiabs setup --harness gemini
GitHub Copilot CLIcopilotabs setup --harness copilot
OpenCodeopencodeabs 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

EnvDefaultPurpose
ABS_DB_PATH / ABS_HOME~/.agentbrainsystem/memory.dbwhere the store lives
ABS_EMBED_PROVIDERlocallocal | gemini | voyage
ABS_RECALL_SCOPEprojectrecall isolation: project | global
ABS_GUARD_MODEwarnPreToolUse guard: warn | block
ABS_LLM_BASE_URL / ABS_LLM_MODEL(unset → consolidation off)OpenAI-compatible endpoint for abs consolidate
ABS_AUTO_DISTILLonauto-distill cadence after SessionEnd (needs an LLM): on | off. 0 opts out
DISTILL_MIN_OBS25min observations in a just-ended session for it to be cadence-due
ABS_SELF_HEAL_HOOKSonre-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

License

MIT © 2026 Victor B. Juliani

Ver o original no GitHub

Bom para

Relacionados