memory-boost 0.1.1__tar.gz → 0.2.0__tar.gz

{memory_boost-0.1.1 → memory_boost-0.2.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memory-boost",
-  "version": "0.1.1",
-  "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.",
+  "version": "0.2.0",
+  "description": "Markdown memory your coding agent reads and writes over MCP, with drift reports that flag stale decisions and local digests of your own sessions. Everything stays in a local folder.",
   "author": { "name": "Arnau González", "url": "https://github.com/arnaugonzalez" },
   "homepage": "https://github.com/arnaugonzalez/memory-boost",
   "repository": "https://github.com/arnaugonzalez/memory-boost",
@@ -10,7 +10,7 @@
   "mcpServers": {
     "memory": {
       "command": "uvx",
-      "args": ["--quiet", "--from", "${CLAUDE_PLUGIN_ROOT}", "memory-boost", "serve"]
+      "args": ["--quiet", "memory-boost==0.2.0", "serve"]
     }
   },
   "hooks": {
@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "uvx --quiet --from \"${CLAUDE_PLUGIN_ROOT}\" memory-boost hook session-start",
+            "command": "uvx --quiet memory-boost==0.2.0 hook session-start",
             "timeout": 120
           }
         ]

{memory_boost-0.1.1 → memory_boost-0.2.0}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.2.0 — 2026-10-18
+
+- recall: freshness is now a down-weight on the bm25 score instead of a hard sort, so a strong match is no longer buried under fresher weak ones.
+- Optional semantic recall: `pip install "memory-boost[semantic]"` plus `MEMORY_BOOST_SEMANTIC=1` and a local
+  `embeddinggemma` (Ollama) adds vector search via sqlite-vec. Default mode when on is `hybrid`; `recall --mode`
+  and `MEMORY_BOOST_RECALL_MODE` select `fts`, `semantic` or `hybrid`. Falls back to full-text if Ollama is down.
+  The base install is unchanged.
+  While embedding, `memory-boost index` and `recall` report `embedding N/M chunks…` on stderr (one
+  rewritten line on a terminal, a line every 128 chunks otherwise); stdout and the MCP server stay quiet.
+- `shelf`: park a one-line idea in a wiki page (default `concepts/idea-shelf.md`) from the CLI
+  (`memory-boost shelf "..."`) or the new `memory_shelf` MCP tool, without reading the page.
+- `serve --http [--host 127.0.0.1] [--port 8765]`: the MCP server over streamable HTTP (stateless,
+  JSON responses) at `http://HOST:PORT/mcp`, for one long-lived local server shared by several
+  sessions. stdio stays the default. Requires `mcp>=1.10`.
+- MCP `initialize` reports `serverInfo` as `memory-boost` and its own version (it reported the mcp
+  library's version).
+- Plugin: the MCP server and the session-start hook run the exact release (`uvx memory-boost==0.2.0`)
+  instead of the plugin checkout, as the Claude plugin directory requires pinned launchers. A test
+  fails if any pinned install (plugin, README, `llms-install.md`) drifts from `__version__`.
+- `llms-install.md`: steps an agent (Claude Code, Codex, Cline, Cursor) can follow to install the CLI
+  and register the MCP server over stdio or `serve --http`, with a harness-independent check. The
+  README gains an "Install from your agent" prompt and pins its install commands.
+- `docs/logo-400.png` (400×400, for MCP directories), rendered by `scripts/render-logo.py`.
+
 ## 0.1.1 — 2026-09-26
 
 - README renders on PyPI and in the MCP registry: the demo GIF, the architecture diagram (now an

memory_boost-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# 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.
+
+Releasing: the version lives in `pyproject.toml`, `src/memory_boost/__init__.py`,
+`.claude-plugin/plugin.json` (`version` and both `memory-boost==X` launchers), `server.json`,
+the `memory-boost==X` pins in `README.md` and `llms-install.md`, and a dated `CHANGELOG.md`
+heading. `tests/test_packaging.py` fails until all of them agree.

{memory_boost-0.1.1 → memory_boost-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memory-boost
-Version: 0.1.1
+Version: 0.2.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
@@ -17,7 +17,9 @@ Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development
 Requires-Python: >=3.11
-Requires-Dist: mcp<2,>=1.2
+Requires-Dist: mcp<2,>=1.10
+Provides-Extra: semantic
+Requires-Dist: sqlite-vec>=0.1.6; extra == 'semantic'
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.arnaugonzalez/memory-boost -->
@@ -71,9 +73,9 @@ times.
 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
+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
@@ -84,7 +86,22 @@ brief and the skills in one step; it only needs [uv](https://docs.astral.sh/uv/)
 /plugin install memory-boost@memory-boost
 ```
 
-Other agents, or the CLI on its own: `uv tool install memory-boost` (or `pipx install 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
 
@@ -123,9 +140,11 @@ 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
+   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_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
@@ -143,6 +162,16 @@ it needed a new tool: the data was already on disk. It needed a reader.
 
 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 |
@@ -163,7 +192,8 @@ 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.
+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.
@@ -176,8 +206,30 @@ Reports end with a `next:` line naming the exact command to run.
 <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 `aliases.json`. Under 1,600 lines of Python, one dependency (`mcp`), no
-embeddings, no daemon.
+map other names in `aliases.json`. Under 1,900 lines of Python, one dependency (`mcp`), no
+embeddings unless you opt into semantic recall, no daemon unless you run `serve --http`.
+
+## Semantic recall (optional)
+
+Off by default: `memory_recall` is full-text only and the base install stays one dependency.
+To also match paraphrases and other languages, run a local embedding model:
+
+```bash
+pip install "memory-boost[semantic]==0.2.0"   # adds sqlite-vec
+ollama pull embeddinggemma
+export MEMORY_BOOST_SEMANTIC=1
+memory-boost index                       # embeds the wiki once; later runs embed only changes
+```
+
+The first index of a large wiki on CPU can take minutes: as a rough guide, about 15 minutes for some
+850 documents on a laptop without a GPU (one measurement, not a benchmark). `memory-boost index` and
+`recall` show `embedding N/M chunks…` on stderr while it runs; later runs re-embed only what changed.
+
+Default mode when on is `hybrid` (full-text and vectors fused by weighted reciprocal rank); override
+with `MEMORY_BOOST_RECALL_MODE=fts|semantic|hybrid` or `memory-boost recall --mode`. If Ollama is down,
+recall falls back to full-text and logs a warning. On a private 64-query set (39 literal, 25 paraphrase)
+with a warm index on CPU: paraphrase nDCG@10 0.46 to 0.76, literal 0.80 to 0.85, p50 about 110 ms per query.
+The query set is not published.
 
 ## Configuration
 
@@ -195,7 +247,7 @@ embeddings, no daemon.
 | | 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 | — |
+| Search | FTS5 (+ optional local vectors) | 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 |
@@ -208,7 +260,7 @@ agents already wrote down.
 
 ## Limits / non-goals
 
-- Keyword search only; no embeddings.
+- Full-text search by default; embeddings only with the optional `[semantic]` extra and a local Ollama.
 - `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.

{memory_boost-0.1.1 → memory_boost-0.2.0}/README.md

@@ -49,9 +49,9 @@ times.
 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
+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
@@ -62,7 +62,22 @@ brief and the skills in one step; it only needs [uv](https://docs.astral.sh/uv/)
 /plugin install memory-boost@memory-boost
 ```
 
-Other agents, or the CLI on its own: `uv tool install memory-boost` (or `pipx install 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
 
@@ -101,9 +116,11 @@ 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
+   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_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
@@ -121,6 +138,16 @@ it needed a new tool: the data was already on disk. It needed a reader.
 
 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 |
@@ -141,7 +168,8 @@ 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.
+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.
@@ -154,8 +182,30 @@ Reports end with a `next:` line naming the exact command to run.
 <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 `aliases.json`. Under 1,600 lines of Python, one dependency (`mcp`), no
-embeddings, no daemon.
+map other names in `aliases.json`. Under 1,900 lines of Python, one dependency (`mcp`), no
+embeddings unless you opt into semantic recall, no daemon unless you run `serve --http`.
+
+## Semantic recall (optional)
+
+Off by default: `memory_recall` is full-text only and the base install stays one dependency.
+To also match paraphrases and other languages, run a local embedding model:
+
+```bash
+pip install "memory-boost[semantic]==0.2.0"   # adds sqlite-vec
+ollama pull embeddinggemma
+export MEMORY_BOOST_SEMANTIC=1
+memory-boost index                       # embeds the wiki once; later runs embed only changes
+```
+
+The first index of a large wiki on CPU can take minutes: as a rough guide, about 15 minutes for some
+850 documents on a laptop without a GPU (one measurement, not a benchmark). `memory-boost index` and
+`recall` show `embedding N/M chunks…` on stderr while it runs; later runs re-embed only what changed.
+
+Default mode when on is `hybrid` (full-text and vectors fused by weighted reciprocal rank); override
+with `MEMORY_BOOST_RECALL_MODE=fts|semantic|hybrid` or `memory-boost recall --mode`. If Ollama is down,
+recall falls back to full-text and logs a warning. On a private 64-query set (39 literal, 25 paraphrase)
+with a warm index on CPU: paraphrase nDCG@10 0.46 to 0.76, literal 0.80 to 0.85, p50 about 110 ms per query.
+The query set is not published.
 
 ## Configuration
 
@@ -173,7 +223,7 @@ embeddings, no daemon.
 | | 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 | — |
+| Search | FTS5 (+ optional local vectors) | 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 |
@@ -186,7 +236,7 @@ agents already wrote down.
 
 ## Limits / non-goals
 
-- Keyword search only; no embeddings.
+- Full-text search by default; embeddings only with the optional `[semantic]` extra and a local Ollama.
 - `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.

memory_boost-0.2.0/llms-install.md

@@ -0,0 +1,144 @@
+# Installing memory-boost (instructions for AI agents)
+
+You are an AI coding agent (Claude Code, Codex, Cline, Cursor or similar) asked to install
+memory-boost and register it as an MCP server. Follow these steps in order. Run each check; if one
+fails, stop and report the command and its stderr. Ask the user before you edit a global config
+file (anything under `~`) or write outside the memory home.
+
+What it is: a markdown wiki that agents read and write over MCP (nine `memory_*` tools), plus
+`drift` reports on that memory and `mine` digests of local Claude Code transcripts. Everything is
+local files; nothing is sent anywhere. The optional semantic recall talks only to a local Ollama.
+
+## 1. Requirements
+
+- Python 3.11+ and [uv](https://docs.astral.sh/uv/) (`uv --version`). If uv is missing, ask the
+  user before installing it. `pipx` works too: replace `uv tool install` with `pipx install`.
+- Linux or macOS. Windows is untested.
+
+## 2. Install the CLI (pinned)
+
+```bash
+uv tool install memory-boost==0.2.0
+memory-boost --version          # expect: memory-boost 0.2.0
+```
+
+Check which binary the harness will run: `command -v memory-boost` must be inside `uv tool dir --bin`
+and `memory-boost --version` must print 0.2.0. If it is not found, or another `memory-boost` comes
+first on PATH, put the absolute path `$(uv tool dir --bin)/memory-boost` in the MCP config below
+instead of `memory-boost` (or ask the user before running `uv tool update-shell`).
+
+Without installing anything permanently, use `uvx memory-boost==0.2.0 <command>` instead of
+`memory-boost <command>` everywhere below (MCP config: command `uvx`, args
+`["--quiet", "memory-boost==0.2.0", "serve"]`).
+
+## 3. Create the memory home
+
+```bash
+memory-boost init               # creates the wiki in $MEMORY_BOOST_HOME (default ~/.local/share/memory-boost)
+memory-boost drift              # exit 0; an empty wiki gives an empty report
+```
+
+To see what it does on sample data first: `memory-boost init --example` (only into an empty home).
+To use an existing markdown wiki, set `MEMORY_BOOST_WIKI=/path/to/wiki` in the MCP server's `env`.
+
+## 4. Register the MCP server
+
+Server name: `memory`. Transport: stdio (default). Command: `memory-boost`, args: `["serve"]`.
+If a server named `memory` is already configured (`claude mcp list`, `codex mcp list` or the JSON
+file), ask the user whether to replace it or use another name such as `memory-boost`.
+Pick the block for your harness.
+
+**Claude Code.** If the user wants the full setup (MCP server, session-start hook, skills), tell
+them to run `/plugin marketplace add arnaugonzalez/memory-boost` and then
+`/plugin install memory-boost@memory-boost` themselves, and skip the rest of this step.
+MCP server only:
+
+```bash
+claude mcp add memory -s user -- memory-boost serve      # all projects (global: ask first)
+claude mcp add memory -s project -- memory-boost serve   # this repo only: writes ./.mcp.json
+claude mcp list                                          # expect: memory: memory-boost serve - ✓ Connected
+```
+
+**Codex CLI**:
+
+```bash
+codex mcp add memory -- memory-boost serve
+```
+
+or in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.memory]
+command = "memory-boost"
+args = ["serve"]
+```
+
+**Cline** (`cline_mcp_settings.json`), **Cursor** (`.cursor/mcp.json`), **VS Code, Gemini CLI and
+other JSON configs**:
+
+```json
+{
+  "mcpServers": {
+    "memory": { "command": "memory-boost", "args": ["serve"] }
+  }
+}
+```
+
+### Optional: one shared server over HTTP
+
+For several sessions sharing one long-lived server, run streamable HTTP (stateless, JSON responses).
+It binds to 127.0.0.1 and has no authentication: never expose it on another interface.
+
+```bash
+memory-boost serve --http                 # defaults: --host 127.0.0.1 --port 8765, endpoint /mcp
+claude mcp add --transport http memory -s user http://127.0.0.1:8765/mcp
+```
+
+JSON configs: `{"mcpServers": {"memory": {"type": "streamableHttp", "url": "http://127.0.0.1:8765/mcp"}}}`
+(Cline uses `streamableHttp`; Claude Code's `.mcp.json` uses `"type": "http"`). Codex:
+`url = "http://127.0.0.1:8765/mcp"` under `[mcp_servers.memory]`. The server must already be
+running (a user service or a terminal); this step does not start it for the user.
+
+## 5. Check that the server answers
+
+This talks to the server directly, independent of any harness. Expect `9`:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | memory-boost serve 2>/dev/null | grep -o '"name":"memory_[a-z]*"' | sort -u | wc -l
+```
+
+For the HTTP server: `curl -s -X POST http://127.0.0.1:8765/mcp -H 'Content-Type: application/json'
+-H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'`
+returns `"serverInfo":{"name":"memory-boost","version":"0.2.0"}`.
+
+The MCP tools: `memory_brief`, `memory_recall`, `memory_page`, `memory_save`, `memory_checkpoint`,
+`memory_resume`, `memory_drift`, `memory_lesson`, `memory_shelf`.
+
+## 6. Tell the agent to use it
+
+Add one line to the project's agent instructions (`AGENTS.md`, `CLAUDE.md`, `.clinerules`, Cursor
+rules), after asking the user:
+
+> At session start call `memory_brief` (MCP server `memory`) and follow it. Record decisions with
+> `memory_save`; before `/compact` or a long pause, call `memory_checkpoint`.
+
+Claude Code without the plugin can also inject the brief automatically with a SessionStart hook in
+`~/.claude/settings.json` (global: ask first):
+
+```json
+{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "memory-boost hook session-start" } ] } ] } }
+```
+
+## 7. Report back
+
+Tell the user: the installed version, where the memory home is, which config file you changed and
+the exact entry, the result of the check in step 5, and the first lines of `memory-boost drift`.
+
+## Uninstall
+
+`uv tool uninstall memory-boost`, remove the `memory` entry from the MCP config, and delete the
+memory home only if the user asks (it holds their notes).

{memory_boost-0.1.1 → memory_boost-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memory-boost"
-version = "0.1.1"
+version = "0.2.0"
 description = "Memory that reviews itself: a markdown wiki for coding agents over MCP, plus drift reports on the wiki and digests of your own sessions."
 readme = "README.md"
 license = "MIT"
@@ -17,7 +17,10 @@ classifiers = [
   "Programming Language :: Python :: 3",
   "Topic :: Software Development",
 ]
-dependencies = ["mcp>=1.2,<2"]
+dependencies = ["mcp>=1.10,<2"]
+
+[project.optional-dependencies]
+semantic = ["sqlite-vec>=0.1.6"]
 
 [project.scripts]
 memory-boost = "memory_boost.cli:main"

memory_boost-0.2.0/scripts/eval_recall.py

@@ -0,0 +1,61 @@
+"""Measure recall quality (nDCG@10, hit@5, MRR) and latency (p50) per query split.
+
+--queries points to JSON shaped as {"<split>": [{"q": str, "gold": [key, ...]}]}.
+A key is a page stem (decisions/foo.md -> "foo") or the project name for log.md entries.
+The queries file is supplied by the user and is not versioned in this repo.
+Run with MEMORY_BOOST_HOME pointing at the wiki to evaluate; --mode picks fts|semantic|hybrid.
+"""
+import argparse
+import json
+import math
+import statistics
+import time
+from pathlib import Path
+
+from memory_boost import core
+
+
+def recall_keys(query: str, historic: bool, mode: str | None) -> list[str]:
+    keys: list[str] = []
+    for r in core.recall(query, limit=10, include_historic=historic, mode=mode):
+        key = r["project"] if r["kind"] == "log" else Path(r["path"]).stem
+        if key not in keys:
+            keys.append(key)
+    return keys[:10]
+
+
+def score(keys: list[str], gold: list[str]) -> dict[str, float]:
+    gold_set = set(gold)
+    rank = next((i + 1 for i, k in enumerate(keys) if k in gold_set), None)
+    dcg = sum(1 / math.log2(i + 2) for i, k in enumerate(keys) if k in gold_set)
+    idcg = sum(1 / math.log2(i + 2) for i in range(min(len(gold_set), 10)))
+    return {
+        "ndcg": dcg / idcg if idcg else 0.0,
+        "hit5": float(rank is not None and rank <= 5),
+        "mrr": 1 / rank if rank else 0.0,
+    }
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--queries", type=Path, required=True, help="JSON file with query splits")
+    ap.add_argument("--historic", action="store_true", help="include historic pages")
+    ap.add_argument("--mode", choices=core.RECALL_MODES, default=None, help="recall mode to evaluate")
+    args = ap.parse_args()
+    splits = json.loads(args.queries.read_text(encoding="utf-8"))
+    for split, items in splits.items():
+        scores, times = [], []
+        for it in items:
+            t0 = time.perf_counter()
+            keys = recall_keys(it["q"], args.historic, args.mode)
+            times.append((time.perf_counter() - t0) * 1000)
+            scores.append(score(keys, it["gold"]))
+        n = len(scores) or 1
+        mean = {m: sum(s[m] for s in scores) / n for m in ("ndcg", "hit5", "mrr")}
+        p50 = statistics.median(times) if times else 0.0
+        print(f"{split}: nDCG@10 {mean['ndcg']:.3f}  hit@5 {mean['hit5']:.3f}  MRR {mean['mrr']:.3f}  "
+              f"p50 {p50:.0f} ms")
+
+
+if __name__ == "__main__":
+    main()

memory_boost-0.2.0/scripts/render-logo.py

@@ -0,0 +1,25 @@
+"""Render docs/logo-400.png (Cline / Glama logo) in the docs/social.png palette.
+
+    uv run --no-project --with pillow python scripts/render-logo.py docs/logo-400.png
+"""
+import sys
+
+from PIL import Image, ImageDraw, ImageFont
+
+out = sys.argv[1]
+S = 4  # supersample
+W = 400 * S
+img = Image.new("RGB", (W, W), "#1e1e2e")
+d = ImageDraw.Draw(img)
+bold = "/usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf"
+reg = "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"
+pad = 40 * S
+d.rounded_rectangle([pad - 4*S, 92*S, W - pad + 4*S, 300*S], radius=18*S,
+                    fill="#181825", outline="#313244", width=2*S)
+f_big = ImageFont.truetype(bold, 78 * S)
+f_small = ImageFont.truetype(reg, 24 * S)
+d.text((pad + 16*S, 110*S), "memory", font=f_big, fill="#f5e0dc")
+d.text((pad + 16*S, 195*S), "-boost", font=f_big, fill="#f5e0dc")
+d.text((pad + 16*S, 48*S), "$ drift", font=f_small, fill="#89b4fa")
+d.text((pad + 16*S, 318*S), "reads it back.", font=f_small, fill="#a6e3a1")
+img.resize((400, 400), Image.LANCZOS).save(out, optimize=True)

{memory_boost-0.1.1 → memory_boost-0.2.0}/scripts/smoke.sh

@@ -43,7 +43,7 @@ assert init["result"]["serverInfo"]["name"], init
 call({"jsonrpc": "2.0", "method": "notifications/initialized"}, reply=False)
 tools = {t["name"] for t in call({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})["result"]["tools"]}
 p.terminate()
-assert len(tools) == 8 and "memory_drift" in tools, tools
+assert len(tools) == 9 and {"memory_drift", "memory_shelf"} <= tools, tools
 print("mcp tools:", ", ".join(sorted(tools)))
 EOF
 step OK

{memory_boost-0.1.1 → memory_boost-0.2.0}/server.json

@@ -8,12 +8,12 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/arnaugonzalez/memory-boost",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "memory-boost",
-      "version": "0.1.1",
+      "version": "0.2.0",
       "runtimeHint": "uvx",
       "packageArguments": [{ "type": "positional", "value": "serve" }],
       "transport": { "type": "stdio" }

{memory_boost-0.1.1 → memory_boost-0.2.0}/src/memory_boost/__init__.py

@@ -1,3 +1,3 @@
 """Shared, file-based memory for coding agents (MCP server + CLI + hooks)."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"