# Brainstack

> Auditable memory for AI coding agents: human-gated, git-synced, model-agnostic recall with provenance and replay. Works with Claude Code, Codex, Cursor.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mustafa-bharmal-shipveho-brainstack`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mustafa-bharmal-shipveho](https://agentstack.voostack.com/s/mustafa-bharmal-shipveho)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mustafa-bharmal-shipveho](https://github.com/mustafa-bharmal-shipveho)
- **Source:** https://github.com/mustafa-bharmal-shipveho/brainstack

## Install

```sh
agentstack add mcp-mustafa-bharmal-shipveho-brainstack
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/make_demo_brain.py) (placeholder names only, safe to publish). Regenerate with `make demo` (requires [vhs](https://github.com/charmbracelet/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

```bash
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:

```bash
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:

```bash
./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/`:

```bash
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:

```bash
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`:

```bash
./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:

```bash
./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](https://github.com/mustafa-bharmal-shipveho)
- **Source:** [mustafa-bharmal-shipveho/brainstack](https://github.com/mustafa-bharmal-shipveho/brainstack)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mustafa-bharmal-shipveho-brainstack
- Seller: https://agentstack.voostack.com/s/mustafa-bharmal-shipveho
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.