memory-boost 0.1.0__tar.gz

memory_boost-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "memory-boost",
+  "description": "memory-boost: memory for coding agents that reviews itself.",
+  "owner": { "name": "Arnau González", "url": "https://github.com/arnaugonzalez" },
+  "plugins": [
+    {
+      "name": "memory-boost",
+      "source": "./",
+      "description": "Markdown memory over MCP, a session-start brief, drift reports, session digests and /retro lessons."
+    }
+  ]
+}

memory_boost-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "memory-boost",
+  "version": "0.1.0",
+  "description": "Memory that reviews itself: a markdown wiki your agents read and write over MCP, plus drift reports on that memory and local digests of your own sessions.",
+  "author": { "name": "Arnau González", "url": "https://github.com/arnaugonzalez" },
+  "homepage": "https://github.com/arnaugonzalez/memory-boost",
+  "repository": "https://github.com/arnaugonzalez/memory-boost",
+  "license": "MIT",
+  "keywords": ["memory", "mcp", "drift", "retrospective", "session-analytics", "context"],
+  "mcpServers": {
+    "memory": {
+      "command": "uvx",
+      "args": ["--from", "${CLAUDE_PLUGIN_ROOT}", "memory-boost", "serve"]
+    }
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uvx --from \"${CLAUDE_PLUGIN_ROOT}\" memory-boost hook session-start",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}

memory_boost-0.1.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,14 @@
+---
+name: Bug report
+about: Something does not work as documented
+---
+
+**Harness and version** (Claude Code, Codex, Cursor…):
+**memory-boost version** (`memory-boost --version`):
+**OS / Python:**
+
+**What you did**
+
+**What happened** (include `memory-boost` stderr if any)
+
+**What you expected**

memory_boost-0.1.0/.github/ISSUE_TEMPLATE/harness.md

@@ -0,0 +1,8 @@
+---
+name: Harness support
+about: Report how memory-boost works (or not) in a harness
+---
+
+**Harness and version:**
+**MCP config you used:**
+**Does the harness have a session-start hook?** (link to its docs)

memory_boost-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+on:
+  push:
+  pull_request:
+
+permissions: {}   # every job states what it needs; nothing here writes
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6.8.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uvx ruff check .
+      - run: uv run pytest
+      - run: uv build && uvx twine check dist/*
+
+  # G4 automated: install the built wheel as a stranger would and run the README quickstart.
+  smoke:
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6.8.0
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - run: uv tool install dist/*.whl && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - run: bash scripts/smoke.sh

memory_boost-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,154 @@
+# Push a tag vX.Y.Z whose number matches pyproject.toml: tests, builds, installs the wheel on
+# Linux and macOS, publishes to PyPI with Trusted Publishing (no token stored anywhere) after a
+# manual approval on the `pypi` environment, creates the GitHub release from CHANGELOG.md, then
+# installs from PyPI and smoke-tests again.
+#
+# Hardening: actions pinned to commit SHAs, no default token permissions, no persisted git
+# credentials, no dependency cache (a poisoned cache could reach the publish job).
+name: Release
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+concurrency:            # never two releases at once; never cancel one half-way
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6.8.0
+        with:
+          python-version: "3.12"
+          enable-cache: false
+      - name: Tag matches pyproject version
+        run: |
+          v=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')
+          test "${GITHUB_REF_NAME#v}" = "$v" || { echo "tag $GITHUB_REF_NAME != version $v"; exit 1; }
+      - name: CHANGELOG has a dated entry for this version
+        run: grep -qE "^## ${GITHUB_REF_NAME#v} — [0-9]{4}-[0-9]{2}-[0-9]{2}" CHANGELOG.md
+      - run: uv sync && uvx ruff check . && uv run pytest -q
+      - run: uv build && uvx twine check dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  smoke:
+    needs: build
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6.8.0
+        with:
+          enable-cache: false
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - run: uv tool install dist/*.whl && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - run: bash scripts/smoke.sh
+
+  publish:
+    needs: smoke
+    runs-on: ubuntu-latest
+    environment: pypi          # requires the maintainer's approval (set by go-public.sh)
+    permissions:
+      id-token: write          # Trusted Publishing: short-lived OIDC token, nothing stored
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - name: Release notes from CHANGELOG.md
+        run: awk -v v="${GITHUB_REF_NAME#v}" '$0 ~ "^## "v" " {on=1; next} /^## / {on=0} on' CHANGELOG.md > notes.md
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file notes.md
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # Official MCP registry (Glama, PulseMCP, mcp.so and others index from it). Runs after PyPI has
+  # the release, because the registry verifies ownership from the `mcp-name:` line of the README
+  # published there. The publisher binary is pinned and checksum-verified like every action here.
+  mcp-registry:
+    needs: verify-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write          # GitHub OIDC login to the registry; nothing stored
+    env:
+      PUBLISHER_VERSION: "1.8.1"
+      PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+      - name: Install mcp-publisher (pinned, checksum-verified)
+        run: |
+          curl -sSfL -o mcp-publisher.tar.gz \
+            "https://github.com/modelcontextprotocol/registry/releases/download/v${PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz"
+          echo "${PUBLISHER_SHA256}  mcp-publisher.tar.gz" | sha256sum -c -
+          tar xzf mcp-publisher.tar.gz mcp-publisher
+      - name: server.json matches the tag
+        run: |
+          python3 -c 'import json,os; d=json.load(open("server.json")); v=os.environ["GITHUB_REF_NAME"][1:]; assert d["version"]==v and d["packages"][0]["version"]==v, d["version"]'
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish
+
+  verify-pypi:
+    needs: publish
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e  # v6.8.0
+        with:
+          enable-cache: false
+      - name: Install from PyPI (retry while the index propagates)
+        run: |
+          for _ in $(seq 1 10); do
+            uv tool install --refresh "memory-boost==${GITHUB_REF_NAME#v}" && break
+            sleep 30
+          done
+          command -v memory-boost >/dev/null || test -x "$HOME/.local/bin/memory-boost"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: The README quickstart form (uvx, no install) resolves the release
+        run: uvx --refresh "memory-boost@${GITHUB_REF_NAME#v}" --version
+      - run: bash scripts/smoke.sh

memory_boost-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+uv.lock
+.demo/

memory_boost-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 — 2026-09-26
+
+First public release.
+
+- Claude Code plugin (`/plugin install memory-boost@memory-boost`): MCP server, session-start
+  hook and skills in one step. Listed in the official MCP registry as
+  `io.github.arnaugonzalez/memory-boost`.
+- Release pipeline hardened: actions pinned to SHAs, no default token permissions, no cache in
+  release jobs, PyPI publish gated by manual approval; zizmor, pip-audit and bandit in preflight.
+- Example wiki shows one finding of each drift kind; `MEMORY_BOOST_TODAY` pins the date for
+  reproducible reports and tests.
+- CLI contract for agents: stdout = data, stderr = `error:` + `fix:`, exit 0/1/2, `--json` on every
+  reading command (with `version`), reports end with a `next:` command; `/memory-boost` router skill.
+- MCP server (stdio) with `memory_brief`, `memory_recall`, `memory_page`, `memory_save`,
+  `memory_checkpoint`, `memory_resume`, `memory_drift`, `memory_lesson`.
+- Markdown wiki store under `MEMORY_BOOST_HOME`; SQLite FTS5 index refreshed incrementally on
+  every recall.
+- Freshness labels (current / unclassified / review / historic / superseded); decisions carry
+  `status:` and `review_by:`.
+- `memory-boost drift`: decisions past review, superseded without successor, silent projects,
+  busy projects with no decisions, checkpoints left open. Top findings injected in the brief.
+- `memory-boost mine`: aggregate digest of local Claude Code transcripts (tools, failed
+  commands, re-reads, subagent fan-out, checkpoint discipline). Contents never leave the machine.
+- `memory-boost lesson` / `lessons`: `concepts/` pages with `applies_when:` that reach other
+  projects through their `tags:`; `/retro` skill to write them at session end.
+- `memory-boost hook session-start` for Claude Code `SessionStart` (startup, resume, compact).
+- `memory-boost init --example` seeds a small example wiki and four synthetic transcripts.

memory_boost-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+```bash
+uv sync
+uv run pytest
+uvx ruff check .
+```
+
+Keep the core stdlib-only (the `mcp` package is the single runtime dependency) and keep
+the hook path fast: `memory-boost hook` must not import `mcp`. Open an issue before
+large changes.

memory_boost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnau González
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memory_boost-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: memory-boost
+Version: 0.1.0
+Summary: Memory that reviews itself: a markdown wiki for coding agents over MCP, plus drift reports on the wiki and digests of your own sessions.
+Project-URL: Repository, https://github.com/arnaugonzalez/memory-boost
+Project-URL: Issues, https://github.com/arnaugonzalez/memory-boost/issues
+Project-URL: Changelog, https://github.com/arnaugonzalez/memory-boost/blob/main/CHANGELOG.md
+Author: Arnau González
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,codex,llm,mcp,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.2
+Description-Content-Type: text/markdown
+
+<!-- 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="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 init --example   # sample wiki with five kinds of rot + four synthetic transcripts
+uvx memory-boost drift            # what in that memory is stale, orphaned or never written down
+uvx memory-boost 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` (or `pipx install memory-boost`).
+
+## 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. Eight MCP
+   tools for any harness: `memory_brief`, `memory_recall`, `memory_page`, `memory_save`,
+   `memory_checkpoint`, `memory_resume`, `memory_drift`, `memory_lesson`.
+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"]`.
+
+| 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 the package; 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
+
+```mermaid
+flowchart LR
+  A[Claude Code / Codex / Cursor] -->|MCP stdio| S[memory-boost serve]
+  H[SessionStart hook] --> B[memory-boost hook]
+  S --> W[(wiki/*.md + log.md)]
+  S --> K[(checkpoints/*.json)]
+  D[memory-boost drift] --> W
+  D --> K
+  M[memory-boost mine] --> T[(~/.claude/projects/*.jsonl)]
+  D --> R[report + brief injection]
+  M --> R
+  W -.incremental refresh.-> I[(SQLite FTS5)]
+```
+
+The project is resolved from the working directory name (`~/work/acme-api` → `projects/acme-api.md`);
+map other names in `aliases.json`. Under 1,600 lines of Python, one dependency (`mcp`), no
+embeddings, no daemon.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MEMORY_BOOST_HOME` | `$XDG_DATA_HOME/memory-boost` | Wiki, events, checkpoints, `aliases.json` |
+| `MEMORY_BOOST_WIKI` | `$MEMORY_BOOST_HOME/wiki` | Point at an existing wiki (e.g. a git repo) |
+| `MEMORY_BOOST_INDEX` | `$XDG_CACHE_HOME/memory-boost/index-<hash>.db` | Search index |
+| `MEMORY_BOOST_CHECKPOINTS` | `$MEMORY_BOOST_HOME/checkpoints` | Checkpoint directory |
+| `MEMORY_BOOST_TRANSCRIPTS` | `~/.claude/projects` | Where `mine` looks (several dirs: `a:b`) |
+| `MEMORY_BOOST_TODAY` | today (UTC) | Pin the date for reproducible reports |
+
+## vs. alternatives
+
+| | memory-boost | [basic-memory](https://github.com/basicmachines-co/basic-memory) | [claude-mem](https://github.com/thedotmack/claude-mem) | [agent-retro](https://github.com/giannimassi/agent-retro) |
+|---|---|---|---|---|
+| Store | Markdown wiki you edit | Markdown | Captured observations | None (prompt skill) |
+| Search | FTS5 | FTS + vectors | FTS + vectors | — |
+| Freshness / review dates | Yes | No | No | — |
+| Drift report over memory | Yes | No | No | No |
+| Session analytics | Yes (aggregates, local) | No | No | LLM reads the conversation |
+| Parallel-session awareness | Yes | No | No | — |
+| License | MIT | AGPL-3.0 | Apache-2.0 | ? |
+
+Want better search, more integrations and a community? Use basic-memory. Want everything
+captured automatically? claude-mem. Use memory-boost if you want to *learn from* what your
+agents already wrote down.
+
+## Limits / non-goals
+
+- Keyword search only; no embeddings.
+- `mine` understands Claude Code transcripts today. Codex is on the roadmap.
+- Reports are as good as the wiki: an empty wiki yields an empty `drift`.
+- Single user, local files. Linux and macOS; Windows untested.
+- The wiki is read by your agents as instructions. Only use a wiki you trust; see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT