Brainstack

brainstack

Agent memory you can audit.

[](https://github.com/mustafa-bharmal-shipveho/brainstack/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml)

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

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](demo/demo.tape) against a fully synthetic brain built by [demo/make_demo_brain.py](demo/makedemobrain.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:

| Surface | What it does | Opt out | |---|---|---| | ~/.claude/settings.json | Registers 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/.cursorrules | Sentinel-delimited recall-first directive blocks | --no-recall-first | | Scheduler | launchd agents on macOS / systemd user timers on Linux, for hourly sync + nightly dream | --no-launchd | | Background session scanner | Continuously rolls newly written agent sessions into the brain | --no-auto-migrate | | Migrate discovery | Prompts before importing existing Claude / Codex / Cursor memory | --skip-migrate | | ~/.local/bin/recall, ~/.agent/, ~/.config/recall/ | CLI symlink, your brain, recall config | Always 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:/.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:/.git
git add . && git commit -m "Initial brain" && git push -u origin main

Full sync architecture: [docs/git-sync.md](docs/git-sync.md).

Customize your install

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

| Flag | Skips | Reason you might | |---|---|---| | --minimal | Everything except the brain, the recall CLI, and recall config | Smallest footprint; add pieces later with the --setup-X flags | | --skip-migrate | Interactive scan-and-import of existing Claude / Codex / Cursor memory | Start with an empty brain | | --no-auto-migrate | Background scanner that pulls new agent sessions into the brain | Trigger migrate manually instead | | --no-launchd | Hourly sync + nightly dream scheduler (launchd agents on macOS, systemd user timers on Linux) | You want to script the schedule yourself | | --no-recall-first | Recall-first directive in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.cursor/.cursorrules | You don't use those agents, or wire elsewhere | | --no-auto-recall | Claude Code UserPromptSubmit hook firing recall on every prompt | Want 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.

| Capability | brainstack | claude-mem | SuperBrain | basic-memory | Claude Code native memory | Mem0 | |---|---|---|---|---|---|---| | Plain markdown you own (git-syncable) | yes | no (database store) | no | yes | partial (local files, no sync story) | no (cloud-default SDK) | | Human review gate before durable memory | yes | no | no | no | no | no | | Proactive injection at every prompt | yes (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 retrieval | yes | partial | partial | partial (search, not hybrid) | no | yes | | Distilled lessons, not transcripts | yes | partial (compressed transcripts) | partial | partial (agent-written notes) | partial | partial (facts, not lessons) | | Consolidation loop with review | yes | no | no | no | no | no | | Provenance + context replay | yes | no | no | no | no | no | | Model/agent agnostic | yes | yes | no (Claude Code only) | yes | no (Claude only) | yes | | License posture | Apache 2.0, no CLA | Apache 2.0 | check | AGPL-or-check | proprietary | Apache 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](eval/RESULTS.md)) on a labeled set with distractor documents and indirectly-worded questions:

| Condition | recall@1 | recall@5 | MRR | answer in top-5 context | |---|---|---|---|---| | With recall | 0.905 | 1.000 | 0.940 | 100% | | Empty brain | 0.000 | 0.000 | 0.000 | 0% |

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:

| Layer | Purpose | |---|---| | Distillation | The 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. | | Storage | Plain markdown + JSONL under ~/.agent/: a private git repo you can read, diff, and grep. | | Retrieval | recall 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. | | Runtime | Context budgets, eviction policy, and replay of exactly what brainstack injected, and when. |

Useful commands:

| Command | Use | |---|---| | 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 | Archive a lesson by name/substring match. | | recall trace | Walk a lesson's provenance chain: source, who wrote it, session, review status, originating digest. | | recall pending --review | Human review for staged memory candidates. | | recall reindex | Rebuild the retrieval cache after large imports/edits. | | recall stats --since 7d | Inspect auto-recall usage and latency. | | recall doctor | Diagnose wiring: hook interpreter, model cache, retrieval mode, scanner, install root. Run this FIRST when something looks wrong. | | recall runtime replay | Reconstruct what entered the agent's context, from logs. |

Retrieval details and benchmark notes: [recall/README.md](recall/README.md). Runtime design: [docs/runtime.md](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

| Name | What it is | |---|---| | brainstack | The project (this repo). | | recall | The CLI. | | recall-brain | The Python package. | | ~/.agent/ | Your brain: a private git repo of markdown and JSONL. |

Where things live

| Path | What it holds | |---|---| | The brainstack clone | Permanent 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/recall | CLI 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](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](docs/git-sync.md).

Claude Code runtime hooks

The full install registers auto-recall hooks in ~/.claude/settings.json, with your con

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mustafa-bharmal-shipveho
• Source: mustafa-bharmal-shipveho/brainstack
• License: Apache-2.0

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