memory-boost

<!-- mcp-name: io.github.arnaugonzalez/memory-boost -->
<h1 align="center">memory-boost</h1>

<p align="center"><em>Memory for coding agents that reviews itself.</em></p>

<p align="center">
  <a href="https://github.com/arnaugonzalez/memory-boost/actions/workflows/ci.yml"><img src="https://github.com/arnaugonzalez/memory-boost/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT">
  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/arnaugonzalez/memory-boost/main/docs/demo.gif" alt="memory-boost drift, mine and lessons running on the bundled example data" width="92%"><br>
  <sub>drift, mine and lessons on the bundled example data · everything runs locally</sub>
</p>

<p align="center">
  <a href="#try-it-in-30-seconds">Try it</a> ·
  <a href="#what-it-answers">What it answers</a> ·
  <a href="#connect-your-harness">Connect your agent</a> ·
  <a href="#how-it-works">How it works</a> ·
  <a href="#vs-alternatives">vs. alternatives</a>
</p>

**Your agents write everything down. Nobody reads it back.**

Every memory tool for coding agents helps them remember *more*. None of them mention that half of
what they remember expired in July. memory-boost keeps a plain-markdown memory your agents read
and write over MCP, and then does the unglamorous part: it audits that memory and your own
sessions, and tells you what drifted. Politely, with numbers.

Think of it as a code review for what your agents remember and a fitness tracker for how you work
with them. Mostly the fitness tracker: `mine` told me my most-failed command was `cd`. Sixty-nine
times.

## What it answers

| You wonder… | memory-boost answers |
|---|---|
| Which decisions quietly expired while we were busy shipping? | `drift`: *review_by 2026-07-08, 78 days ago* |
| Which "active" projects actually died months ago? | `drift`: *last session 161 days ago; still listed as live* |
| We fixed this exact bug in another repo. How? | `lessons`: the fix follows you to every project with the same stack |
| Why does my agent keep re-reading the same file? | `mine`: *one file, read 18 times* |
| Is my agent spawning 20 subagents behind my back? | `mine`: yes, and in which session |
| Where was I before `/compact` ate my context? | The session-start hook puts your checkpoint back |

## Try it in 30 seconds

No install needed; the wiki lands in `~/.local/share/memory-boost`:

```bash
uvx memory-boost==0.2.0 init --example   # sample wiki with five kinds of rot + four synthetic transcripts
uvx memory-boost==0.2.0 drift            # what in that memory is stale, orphaned or never written down
uvx memory-boost==0.2.0 mine             # now on your real ~/.claude/projects: aggregates only
```

To keep it in Claude Code, install the plugin. It brings the MCP server, the session-start
brief and the skills in one step; it only needs [uv](https://docs.astral.sh/uv/) on your PATH.

```
/plugin marketplace add arnaugonzalez/memory-boost
/plugin install memory-boost@memory-boost
```

Other agents, or the CLI on its own: `uv tool install memory-boost==0.2.0` (or
`pipx install memory-boost==0.2.0`). Or let your agent do it: see [Install from your agent](#install-from-your-agent).

## Install from your agent

Paste this into Claude Code, Codex, Cline or Cursor:

> Install memory-boost 0.2.0 by following
> https://github.com/arnaugonzalez/memory-boost/blob/main/llms-install.md : install the CLI with
> `uv tool install memory-boost==0.2.0`, run `memory-boost init`, register `memory-boost serve`
> as a stdio MCP server named `memory`, check that it answers with nine `memory_*` tools, then run
> `memory-boost drift` and show me the output. Ask me before writing outside the memory home
> (`~/.local/share/memory-boost`) or editing any global agent config.

The agent-oriented steps (stdio and `serve --http`, per harness, with checks) are in
[llms-install.md](https://github.com/arnaugonzalez/memory-boost/blob/main/llms-install.md).

## On a real machine

Five weeks of the author's own daily use: 29 decisions, 24 projects, 657 Claude Code transcripts.
Output as produced; only project and file names are replaced.

```
$ memory-boost drift
# Drift report — 2026-09-24
29 decisions · 24 projects · 204 log entries · 33 open checkpoints · **20 findings**

## decision-expired (9)
- deploy-via-bastion — review_by 2026-07-08 (78 days ago); revisit or mark historic
- bot-guardrails — review_by 2026-07-08 (78 days ago); revisit or mark historic
  …
## project-no-decisions (2)
- thesis-solver — 20 sessions logged, 0 decisions tagged 'thesis-solver': the learning lives only in transcripts
## project-silent (5)
- mood-api — last session 2026-04-16 (161 days ago); still listed as live
  …

$ memory-boost mine
# Session digest — 2026-09-24
sessions      80 with ≥20 turns
tools         Bash 5956 · Edit 860 · Read 692 · Write 493 · Agent 203 · ToolSearch 138
bash          5956 calls, 159 failed (2.7%); most failed: cd (69), sleep (12), ssh (9), pkill (8), ls (7)
bash/edit     4.4x; extreme: crm-wt-f11 107.5x, sandbox 70.0x, sandbox 54.0x
reads         692 calls, 131 re-reads of a file already read (19%); top: …/apply_email.py ×18
discipline    62 long sessions (≥60 turns): 47 never checkpointed, 29 never saved
subagents     203 spawned in 44 sessions; max in one session: 20
```

Every line is a habit to change, a decision to revisit, or a rule worth writing down. None of
it needed a new tool: the data was already on disk. It needed a reader.

## What it is

1. **A wiki you own.** `projects/*.md`, `decisions/*.md`, `concepts/*.md`, `log.md`. Plain
   markdown; edit by hand, keep it in git. SQLite FTS5 index as a disposable cache. Nine MCP
   tools for any harness: `memory_brief`, `memory_recall`, `memory_page`, `memory_save`,
   `memory_checkpoint`, `memory_resume`, `memory_drift`, `memory_lesson`, `memory_shelf`.
   `memory_shelf` (CLI: `memory-boost shelf "idea"`) appends a dated one-line idea to
   `concepts/idea-shelf.md` without the agent reading the page back.
2. **Freshness as data.** Decisions carry `status:` and `review_by:`. Search results are tagged
   `current / unclassified / review / historic / superseded`, current first.
3. **Session checkpoints** that survive `/compact`, with one line per *other* active session on
   the same project so parallel agents don't collide.
4. **`drift`** reads the wiki and reports what expired, what went silent, what was never written
   down and what was left half-done. The current project's top findings go into every session brief.
5. **`mine`** reads your local Claude Code transcripts and reports tool usage, failed commands,
   re-reads, subagent fan-out and checkpoint discipline. Aggregates only: no prompt, command or
   file content is stored or printed, so the digest is safe to paste anywhere.
6. **`lessons`**: `concepts/` pages with `applies_when: [tags]`. A project page that lists
   matching `tags:` gets those lessons in its brief, so what worked in one repo reaches the next.
   The `/retro` skill writes them at session end.

## Connect your harness

MCP server (all harnesses): command `memory-boost`, args `["serve"]`.

To share one server between several sessions, run it over streamable HTTP (stateless, JSON
responses) and point each harness at `http://127.0.0.1:8765/mcp`:

```bash
memory-boost serve --http                      # --host 127.0.0.1 --port 8765 are the defaults
claude mcp add --transport http memory -s user http://127.0.0.1:8765/mcp
```

It binds to loopback by default and has no authentication: keep it there.

| Harness | MCP registration | Context at session start |
|---|---|---|
| Claude Code (plugin) | `/plugin install memory-boost@memory-boost` | Included: hook, MCP server, skills |
| Claude Code (manual) | `claude mcp add memory -s user -- memory-boost serve` | Hook below (startup, resume, compact); `mine` reads its transcripts |
| Codex CLI | `codex mcp add memory -- memory-boost serve` | `AGENTS.md`: "call `memory_brief` first" |
| Cursor / VS Code / Gemini CLI | stdio entry in their `mcp.json` / `settings.json` | Same line in rules (hook adapters: roadmap) |

Manual Claude Code hook (`~/.claude/settings.json`), not needed with the plugin:

```json
{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "memory-boost hook session-start" } ] } ] } }
```

On `startup`/`resume` it injects ~1k tokens: catalog, the project's context and last sessions,
its drift, lessons from other projects, your open checkpoint. On `compact` only this session's
checkpoint. It never blocks session start: on any error it prints nothing.

Skills: `/memory-boost` (router: when to run what), `/save-session`, `/restore-session`,
`/retro`. The plugin installs them as `/memory-boost:retro` and so on; without it, copy
`skills/*` into `~/.claude/skills/`. The first session after installing the plugin takes a few
extra seconds while uv fetches `memory-boost==0.2.0` and its dependencies from PyPI (the only
network access the plugin makes); later sessions start in about 0.2 s.

CLI contract for agents: data on stdout, errors on stderr with a `fix:` line, `--json` on every
reading command (with a `version` field), exit 0 = trust stdout, 1 = not found, 2 = bad input.
Reports end with a `next:` line naming the exact command to run.

## How it works

<img src="https://raw.githubusercontent.com/arnaugonzalez/memory-boost/main/docs/architecture.png" alt="Agents talk to memory-boost serve over MCP; the hook injects the brief; drift reads the wiki and checkpoints; mine reads local transcripts; both feed reports and the brief" width="100%">

<sub>Source: [docs/architecture.mmd](https://github.com/arnaugonzalez/memory-boost/blob/main/docs/architecture.mmd)</sub>

The project is resolved from the working directory name (`~/work/acme-api` → `projects/acme-api.md`);
map other names in `alia