convez.ai
MCP ServerDevOps & InfraestruturaAvançado
mustafa-bharmal-shipveho

Brainstack

mustafa-bharmal-shipveho/brainstack

Memória auditável para agentes de código com versionamento git e controle humano

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que fornece memória auditável para agentes de IA: aprende de sessões anteriores, armazena conhecimento em markdown versionado no git, e injeta contexto relevante automaticamente. Implementa gate humano, rastreamento de proveniência e replay exato do que entrou no contexto do agente.

Instalação

$npx convez-ai mustafa-bharmal-shipveho/brainstack

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
1
Forks
1
Acompanhando
0
Saúde
85%
Último commit
há 1 mês
Versão
v0.5.1
Issues abertas
2
Contribuidores
1

Casos de uso

  • Agentes que precisam reter aprendizados entre sessões
  • Auditoria de decisões e contexto usado por IA
  • Equipes que querem controlar e revisar conhecimento compartilhado

Veredito

Solução madura e bem-arquitetada para um problema real: agentes esquecem entre sessões. Implementação local-first, sem telemetria, com gates humanos e git como fonte da verdade torna-a confiável para ambientes corporativos. Requer Python 3.10+ e familiaridade com CLI.

README

A tradução para o português deste README ainda está na fila.

brainstack

Agent memory you can audit.

CI License: Apache 2.0 Python 3.10 | 3.11 | 3.12 | 3.13

Your coding agents already learn things every session, then forget them by the next one. Brainstack distills those sessions into plain-markdown lessons on your disk, asks you before anything becomes permanent, pushes the right lesson back into your agent on every prompt, before you ask, and can prove it: replay exactly what entered your agent's context, and when. Works with Claude Code, Codex CLI, Cursor, or any MCP-capable client. Your brain is a git repo of markdown you can read, diff, grep, and take with you.

Demo

brainstack: a prompt is auto-enriched with a past lesson, the lesson is traced to its source, and an agent's durable write is refused

Four beats: the per-prompt hook injects a past lesson before you ask; recall trace walks that lesson back to its provenance and originating session; a piped (non-human) recall remember --reviewed is refused while the default write lands staged for your review; recall stats shows the week's auto-recall ROI. Generated from demo/demo.tape against a fully synthetic brain built by demo/make_demo_brain.py (placeholder names only, safe to publish). Regenerate with make demo (requires vhs).

Why you can trust it

  • Apache 2.0, no CLA. Contributors keep their copyright; there is no relicense lever.
  • Zero telemetry. The code makes no network calls of its own.
  • Local-first. Brain, index, and models live on your disk.
  • Exactly three things can leave your machine, each under your control: git pushes to a brain remote you configure (none in the minimal install), a one-time ~210 MB embedding model download on first index, and optional query expansion (--expand, off by default), which sends your query text, never memory bodies, through your own claude or codex CLI.
  • Pushes are secret-scanner gated. Sync refuses to push without trufflehog or gitleaks.
  • Durable lessons are human-gated and carry provenance. Dream candidates require your review; recall remember stages for review by default.

Quickstart

git clone https://github.com/mustafa-bharmal-shipveho/brainstack.git
cd brainstack
./install.sh --minimal
recall query "what did I learn about flaky integration tests"

--minimal installs the brain and the recall CLI, nothing else. It touches only the clone directory, ~/.agent/, ~/.config/recall/, and a recall symlink in ~/.local/bin/. Nothing in ~/.claude/, no daemons, no shell edits.

The full experience

Want everything turned on (auto-recall on every prompt, recall-first directives, hourly sync + nightly dream, the background session scanner) in one command, no prompts:

git clone https://github.com/mustafa-bharmal-shipveho/brainstack.git
cd brainstack
./install.sh --yes

--yes is the "install all options, don't ask me" path. Prefer to see what it does first? Run ./install.sh with no flags: it prints everything it will touch, including an Install root: line showing where the clone and its Python venv will live, and asks once before doing anything (a non-interactive run without --yes falls back to the minimal install). ./install.sh --dry-run prints that same plan and exits without changing anything. If neither trufflehog nor gitleaks is on PATH, the full install offers to install one.

Turn individual pieces off by adding the opt-out flags from the table below (they compose, e.g. ./install.sh --yes --no-launchd --no-auto-migrate).

What the full install touches:

SurfaceWhat it doesOpt out
~/.claude/settings.jsonRegisters auto-recall hooks: recall runs on every Claude Code prompt and injects bounded brain context--no-auto-recall
~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.cursor/.cursorrulesSentinel-delimited recall-first directive blocks--no-recall-first
Schedulerlaunchd agents on macOS / systemd user timers on Linux, for hourly sync + nightly dream--no-launchd
Background session scannerContinuously rolls newly written agent sessions into the brain--no-auto-migrate
Migrate discoveryPrompts before importing existing Claude / Codex / Cursor memory--skip-migrate
~/.local/bin/recall, ~/.agent/, ~/.config/recall/CLI symlink, your brain, recall configAlways installed (the minimal install installs these too)

Back up your brain

A remote is optional. When you want the brain to survive a laptop loss, add one:

./install.sh --brain-remote git@github.com:<you>/<your-private-brain-repo>.git

Hourly sync then commits and pushes ~/.agent/ to that remote. Pushing requires a secret scanner: sync refuses to push without trufflehog or gitleaks on PATH (pass --install-scanner during setup, or brew install trufflehog). Use a private repo; the brain contains personal memory.

Already installed and want to wire a remote by hand? Inside ~/.agent/:

cd ~/.agent
git init && git branch -m main
git remote add origin git@github.com:<you>/<your-private-brain-repo>.git
git add . && git commit -m "Initial brain" && git push -u origin main

Full sync architecture: docs/git-sync.md.

Customize your install

The full install enables everything. Skip any subset by passing flags to ./install.sh:

FlagSkipsReason you might
--minimalEverything except the brain, the recall CLI, and recall configSmallest footprint; add pieces later with the --setup-X flags
--skip-migrateInteractive scan-and-import of existing Claude / Codex / Cursor memoryStart with an empty brain
--no-auto-migrateBackground scanner that pulls new agent sessions into the brainTrigger migrate manually instead
--no-launchdHourly sync + nightly dream scheduler (launchd agents on macOS, systemd user timers on Linux)You want to script the schedule yourself
--no-recall-firstRecall-first directive in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.cursor/.cursorrulesYou don't use those agents, or wire elsewhere
--no-auto-recallClaude Code UserPromptSubmit hook firing recall on every promptWant only agent-driven recall, not the unconditional sweep
--setup-systemd(Adds systemd user timers explicitly; --remove-systemd tears them down)Wire Linux scheduling without re-running the full install
--yes(Accepts the install plan and migrate-discovery prompts non-interactively)CI / scripted installs
--no-prompt(Decline all migrate prompts; still runs the other defaults)CI / scripted installs

Each opt-out is reversible later via the matching --setup-X / --enable-X flag (or --remove-X / --disable-X to undo something later). Run recall doctor any time to see what's enabled.

How it compares

basic-memory is a store your agent has to query. claude-mem captures and recalls automatically, for many agents, but writes durable memory without review. Brainstack distills, asks you first, injects on every prompt, and can replay what the agent knew.

Capabilitybrainstackclaude-memSuperBrainbasic-memoryClaude Code native memoryMem0
Plain markdown you own (git-syncable)yesno (database store)noyespartial (local files, no sync story)no (cloud-default SDK)
Human review gate before durable memoryyesnonononono
Proactive injection at every promptyes (Claude Code today)partial (automatic, session-scoped)partial (Claude Code only)no (agent must query)partial (session-start full-file load)no (SDK query)
Ranked hybrid retrievalyespartialpartialpartial (search, not hybrid)noyes
Distilled lessons, not transcriptsyespartial (compressed transcripts)partialpartial (agent-written notes)partialpartial (facts, not lessons)
Consolidation loop with reviewyesnonononono
Provenance + context replayyesnonononono
Model/agent agnosticyesyesno (Claude Code only)yesno (Claude only)yes
License postureApache 2.0, no CLAApache 2.0checkAGPL-or-checkproprietaryApache 2.0 + hosted

Verified against claude-mem v13.4.x, SuperBrain v0.8.0, basic-memory v0.21.6 as of June 2026; this space moves weekly.

No shipping tool today combines all five of: human-gated durable memory, plain-markdown ownership, every-prompt proactive injection, provenance with context replay, and model-agnostic operation.

Does recall actually help?

A reproducible retrieval A/B (make bench, methodology + caveats) on a labeled set with distractor documents and indirectly-worded questions:

Conditionrecall@1recall@5MRRanswer in top-5 context
With recall0.9051.0000.940100%
Empty brain0.0000.0000.0000%

That is the precondition for usefulness (the right memory is surfaced), not an end-to-end task-success claim. The credible public benchmark is LongMemEval; the harness ingests its format and that run is on the roadmap. Numbers get published whatever they say.

Why not claude-mem?

claude-mem is the category leader and a good default if you want zero-ceremony automatic memory: it is mature, has a real community, and its plugin UX is smooth. Choose brainstack for three things claude-mem does not do: the review gate (nothing becomes durable memory without your sign-off), the readable git-repo brain (markdown you can diff and grep, not an opaque store), and the audit trail (recall runtime replay answers the question automatic memory cannot: did the agent have the right context when it mattered?).

Why not wait for Anthropic?

Claude's memory belongs to Claude; yours should belong to you. A brainstack brain survives switching Claude to Codex to Cursor, survives losing a vendor account, and stays inspectable markdown rather than an opaque store. It keeps the human gate that native auto-memory does not have, and provides replay that no vendor offers. If Anthropic ships all of this for Claude, the same brain still feeds every other agent you run.

What it does

Brainstack has four layers:

LayerPurpose
DistillationThe nightly dream cycle clusters captured events into reviewable candidate lessons; session digests summarize long sessions into searchable markdown, so recall finds past work, not only raw tool calls.
StoragePlain markdown + JSONL under ~/.agent/: a private git repo you can read, diff, and grep.
Retrievalrecall query and the read-only recall-mcp server search memory and imports with hybrid Qdrant + BM25 retrieval; auto-recall injects bounded results into Claude Code on every prompt.
RuntimeContext budgets, eviction policy, and replay of exactly what brainstack injected, and when.

Useful commands:

CommandUse
recall query "..."Search memory and imports.
recall query --mode {hybrid,bm25} "..."Force a retrieval mode (RECALL_MODE env works too). Recall auto-falls back to BM25-only when the embedding stack is unavailable.
recall query --expand "..."LLM-expanded query for hard semantic prompts. Adds one LLM CLI round-trip (~5-20 s); off by default.
recall remember "..."Stage a lesson for review (needs_review by default).
recall remember --reviewed "..."Deliberate durable write that skips the staging gate.
recall forget <query>Archive a lesson by name/substring match.
recall trace <lesson>Walk a lesson's provenance chain: source, who wrote it, session, review status, originating digest.
recall pending --reviewHuman review for staged memory candidates.
recall reindexRebuild the retrieval cache after large imports/edits.
recall stats --since 7dInspect auto-recall usage and latency.
recall doctorDiagnose wiring: hook interpreter, model cache, retrieval mode, scanner, install root. Run this FIRST when something looks wrong.
recall runtime replayReconstruct what entered the agent's context, from logs.

Retrieval details and benchmark notes: recall/README.md. Runtime design: docs/runtime.md.

Review flow

The review gate is the core trust feature: nothing becomes durable semantic memory until you approve it. Two paths feed it:

  • The dream cycle stages candidate lessons in ~/.agent/memory/candidates/.
  • recall remember stages new lessons as needs_review by default.

Both pass through the same human review:

recall pending
recall pending --review

recall remember --reviewed exists for deliberate durable writes that skip staging; use it when you, not an agent, decide a lesson is final.

Optional startup surfaces wire pending-review visibility into Claude Code, Cursor rules, and shell wrappers for AI CLIs listed in ~/.agent/banner/wrapped_tools:

./install.sh --setup-pending-review-all
./install.sh --remove-pending-review-all

Naming map

NameWhat it is
brainstackThe project (this repo).
recallThe CLI.
recall-brainThe Python package.
~/.agent/Your brain: a private git repo of markdown and JSONL.

Where things live

PathWhat it holds
The brainstack clonePermanent runtime infrastructure: the Python venv (~1.1 GB) lives inside it, and the hooks plus the recall symlink point into it. Pick a permanent location before installing.
~/.agent/Your data: lessons, digests, notes, episodic logs.
~/.cache/fastembed/Embedding models (~210 MB, re-downloadable; XDG_CACHE_HOME and FASTEMBED_CACHE_PATH are respected).
~/.config/recall/recall configuration.
~/.local/bin/recallCLI symlink into the clone.
~/Library/LaunchAgents/ (macOS) or systemd user units (Linux)Scheduler entries for hourly sync + nightly dream (full install only).
~/.agent/runtime/logs/Runtime telemetry consumed by recall runtime replay.

Setup details

Most users won't need this section. Read on if you want to understand what's running, opt out of pieces, or troubleshoot.

Requirements detail

  • git, Python 3.10+, macOS or Linux. Windows is supported via WSL2 (run the installer inside your WSL distro; native Windows is on the roadmap)
  • A private git remote is optional: only needed to back up the brain
  • ~210 MB one-time embedding model download to ~/.cache/fastembed/ on the first index. Without it, recall auto-falls back to BM25-only retrieval (--mode / RECALL_MODE control this explicitly)
  • A secret scanner (trufflehog or gitleaks) is needed only for git sync; the full install offers to install one
  • Optional: claude or codex CLI for recall query --expand (off by default; adds one LLM round-trip, ~5-20 s, for hard semantic queries)

First-run note: the first recall query triggers a one-time reindex. Interactive queries are sub-3 s on a typical brain. Per-feature retrieval details: recall/README.md.

Hourly sync + nightly dream cycle

The full install schedules both automatically, selecting the scheduler for your platform: launchd agents on macOS, systemd user timers on Linux. To wire or tear down later:

./install.sh --setup-launchd       # macOS: expands plist templates + launchctl load
./install.sh --remove-launchd      # macOS: unload + delete plists

./install.sh --setup-systemd       # Linux: writes + enables systemd user timers mirroring the launchd schedule
./install.sh --remove-systemd      # Linux: disable + delete the units

Logs land at ~/.agent/dream.log and ~/.agent/sync.log. Full sync architecture: docs/git-sync.md.

Claude Code runtime hooks

The full install registers auto-recall hooks in ~/.claude/settings.json, with your consent at the plan prompt. Opt out with --no-auto-recall. To wire hooks manually (for example after a minimal install):

recall runtime install-hooks

Hooks are registered with the repo venv's Python interpreter; recall doctor verifies the hook interpreter, model cache, retrieval mode, scanner, and install root. Setup details: docs/claude-code-setup.md.

Bring existing memories

The full install discovers ~/.claude/projects/*/memory, ~/.codex/, and ~/.cursor/ and prompts y/n before importing each. If you skipped that (minimal install, --skip-migrate, --no-prompt) or want to import additional sources later:

./install.sh --migrate                                    # interactive discovery
./install.sh --migrate ~/.claude/projects/<slug>/memory   # specific path

For Claude Code memory directories, migration preserves the original at <source>.bak.<timestamp> before wiring the source into brainstack as a symlink. Cursor and Codex imports are snapshot-style.

The full install also turns on a background scanner that continuously rolls newly written agent sessions into the brain. If you opted out via --no-auto-migrate, enable it later with ./install.sh --setup-auto-migrate.

Optional deeper Claude Code mirroring (transcripts + misc dirs into ~/.agent/imports/, no modifications to source):

./install.sh --setup-claude-extras

Tell your agents to use recall first

The full install wires this for you (skip with --no-recall-first). Recall only helps if the agent calls it: without explicit instructions, hosts (Claude Code, Codex CLI, Cursor) tend to default to grep or web search even when the answer is already in your brain.

To wire this later or tear it down:

./install.sh --setup-recall-first-all      # all three host configs
./install.sh --remove-recall-first-all

This injects a brainstack-managed block into:

  • ~/.claude/CLAUDE.md (Claude Code)
  • ~/.codex/AGENTS.md (Codex CLI)
  • ~/.cursor/.cursorrules (Cursor)

with a directive telling the agent: for prior-personal-context questions ("have I dealt with X before?", "what did I learn about Y?"), call recall query "..." (or the recall_query MCP tool) FIRST. The block is delimited by <!-- brainstack-recall-first-start --> sentinels and is idempotent: re-running replaces the bracketed section without touching anything else.

Per-host variants if you only want one: --setup-recall-first-claude, --setup-recall-first-codex, --setup-recall-first-cursor (each with a matching --remove-*).

Use it from Cursor or any MCP client

recall-mcp is a read-only MCP server exposing a single recall_query tool. After installing the package, add it to any MCP-capable client:

{ "mcpServers": { "brainstack": { "command": "recall-mcp" } } }

For Cursor, this one-click deeplink writes that config for you (it still asks you to approve):

Add brainstack to Cursor

A Claude Code plugin marketplace manifest ships at .claude-plugin/marketplace.json, and an MCP-registry server.json is included for uvx-based discovery (publishing to the registries is tracked in the roadmap).

Add more sources

Mirror any folder into recall:

./install.sh --add-source ~/Documents/Engineering-Notes --as kb/eng-notes
./install.sh --list-sources
./install.sh --remove-source kb/eng-notes

Mirrored sources land under ~/.agent/imports/ and are included in recall by default. Be deliberate here: mirrored sources sync to your private brain remote unless you add the destination to ~/.agent/.gitignore.

Manual brain edits via CLI

The daily way to use brainstack is through your host agent (Claude Code, Codex CLI, or Cursor), which calls recall automatically. For times when you want CLI access (adding a one-shot note from a terminal, debugging retrieval, scripting against the brain):

recall remember "always run the exact CI command from the repo config"
recall query "what should I remember before changing CI?"
recall forget ci-command
recall pending --review                  # review staged candidates
recall stats --since 24h                 # see auto-recall ROI
recall doctor                            # diagnose missing wiring

Full retrieval design and benchmarks: recall/README.md.

Safety model

Brainstack assumes your memory may contain sensitive tool-call history, and that recalled text is data, not instructions.

  • Recalled excerpts are sanitized and fenced, with an untrusted-content preamble and per-document provenance labels.
  • Durable lessons are review-gated: dream candidates and recall remember lessons both pass through recall pending --review.
  • Write-path redaction applies the builtin credential patterns plus your redact-private.txt across all adapters.
  • A redaction pre-commit hook and sync-time JSONL scrubbing run before any push.
  • Scheduled sync refuses to push without trufflehog or gitleaks.
  • recall-mcp is read-only.
  • Sentinel locks and atomic writes guard append/rewrite paths; migration keeps backups instead of deleting existing memory directories.

Threat model and redaction policy: docs/redaction-policy.md. What leaves the machine, what doesn't, and known residual risks: docs/privacy-audit.md. Vulnerability reporting and the memory-poisoning model: SECURITY.md.

Known boundaries

  • Per-prompt auto-injection ships for Claude Code today (it depends on Claude Code's UserPromptSubmit hook surface). Codex CLI and Cursor get recall-first directives plus recall-mcp; per-client injection adapters are on the roadmap.
  • Embedded Qdrant is a local cache, not a multi-writer database. Short CLI/MCP use is locked and safe; heavy concurrent agents should use separate XDG_CACHE_HOME values or a shared recall/Qdrant service.
  • Broad natural-language queries may return the right neighborhood rather than the exact memory. Treat lower-score results as context, not authority.
  • The runtime audits what brainstack injects. It cannot inspect or control a model vendor's private KV cache.

Built on agentic-stack

The consolidation pipeline (dream cycle, clustering, promotion, decay) is vendored from codejunkie99/agentic-stack (Apache 2.0), pinned and attributed in NOTICE and UPSTREAM.md. Original to this project: the recall read side (hybrid retrieval CLI + MCP server), every-prompt proactive injection and the replay runtime, the installer and its hardening, and locking/atomicity fixes to the vendored pipeline.

Architecture

~/.agent/
├── memory/
│   ├── episodic/      # append-only captured events
│   ├── candidates/    # staged lessons awaiting review
│   ├── semantic/      # durable lessons, digests, claims
│   ├── personal/      # profile, notes, references
│   └── MEMORY.md      # generated index
├── imports/           # mirrored external sources
├── tools/             # dream, sync, migration, redaction helpers
├── runtime/           # optional context-runtime logs, populated after runtime use
└── .git/              # private brain repo

More detail:

Historical run logs and audit artifacts are preserved under docs/history/.

Upgrade

./upgrade.sh              # default: git pull + refresh brain (one command)
./upgrade.sh --no-pull    # skip the pull (you manage git yourself)

./upgrade.sh does two things:

  1. git pull --ff-only origin main in the brainstack repo so you're on the latest released code. Use --no-pull if you're already on the version you want, or in a CI/release context that handles git separately.
  2. Refreshes ~/.agent/tools, framework memory modules, and runtime helpers while preserving user data under ~/.agent/memory/. Equivalent to ./install.sh --upgrade.

Each upgrade writes the new version to ~/.agent/.brainstack-version, so the next upgrade announces what changed (e.g., Upgraded from 0.4.0 → 0.5.0) and points you at the CHANGELOG for details.

Uninstall

Brainstack is safe to trial: uninstall removes every host-side surface it installed and preserves your memory data by default. The brain at ~/.agent/ (every digest, lesson, note you ever wrote) is the one thing the uninstaller never touches without an explicit opt-in.

./uninstall.sh --dry-run    # print the plan, change nothing
./uninstall.sh              # interactive, with confirmation prompt
./uninstall.sh -y           # skip the prompt (non-interactive)
./uninstall.sh --purge-data # ALSO delete ~/.agent + ~/.config/{recall,brainstack}

(./install.sh --uninstall ... is the equivalent; uninstall.sh is a discoverable wrapper around it.)

What gets removed (default)

  • ~/Library/LaunchAgents/com.user.agent-{dream,sync,migrate,claude-extras}.plist (macOS) or the matching systemd user units (Linux)
  • The brainstack-shell-banner block in ~/.zshrc
  • brainstack-managed blocks in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.cursor/.cursorrules
  • brainstack hook entries in ~/.claude/settings.json
  • The recall / recall-mcp symlinks under ~/.local/bin/
  • The index cache at ~/.cache/recall/ (regenerates on next reindex)

What is preserved

  • ~/.agent/: your memory (digests, lessons, claims, notes, episodic logs)
  • ~/.config/recall/: your recall config
  • ~/.config/brainstack/: your extractor / project / channel configs
  • ~/.cache/fastembed/: downloaded embedding models (delete manually to reclaim ~210 MB)
  • Your remote brain repo on GitHub: the durable backup
  • The brainstack repo clone (delete manually if you want to)

Run ./uninstall.sh --purge-data (explicit opt-in) to also delete ~/.agent/ and the config dirs.

Roadmap

Where this is going, and what is deliberately out of scope: ROADMAP.md.

License

Apache 2.0. See LICENSE and NOTICE.

This is infrastructure shared as-is. Issues and PRs are welcome (CONTRIBUTING.md), but no support obligations are implied.

Ver o original no GitHub

Bom para

Relacionados