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

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

@@ -1,7 +1,7 @@
 {
   "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.",
+  "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": ["--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 --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.2.0/.github/pull_request_template.md

@@ -0,0 +1,6 @@
+**What and why** (one or two lines):
+
+**How I checked it**
+- [ ] `uv run pytest` and `uvx ruff check .` pass
+- [ ] If output changed: `memory-boost drift` / `mine` on the example data still read well
+- [ ] If it touches `mine`: the digest still prints aggregates only (no prompts, commands or paths outside `~`)

memory_boost-0.2.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# 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
+  image, source in `docs/architecture.mmd`) and the security link use absolute URLs. A test keeps
+  relative links out.
+- Plugin: the first session no longer prints uv's download progress (`uvx --quiet`).
+
+## 0.1.0 — 2026-09-26
+
+First public release.
+
+What you get:
+
+- `memory-boost drift`: what in your agents' memory expired, points nowhere, went silent or was
+  never written down. The current project's top findings go into every session brief.
+- `memory-boost mine`: a digest of your local Claude Code transcripts (tools, failed commands,
+  re-reads, subagent fan-out, checkpoint discipline). Aggregates only; contents never leave the
+  machine.
+- `memory-boost lessons` and the `/retro` skill: lessons learned in one project reach every
+  project with the same stack.
+- Claude Code plugin (`/plugin install memory-boost@memory-boost`): MCP server, session-start
+  brief and skills in one step. Also in the official MCP registry as
+  `io.github.arnaugonzalez/memory-boost`.
+- MCP server (stdio) with eight tools: `memory_brief`, `memory_recall`, `memory_page`,
+  `memory_save`, `memory_checkpoint`, `memory_resume`, `memory_drift`, `memory_lesson`.
+- A markdown wiki you own, with freshness labels (current / review / historic / superseded) and
+  `review_by:` dates on decisions; SQLite FTS5 search refreshed on every recall.
+- Session checkpoints that survive `/compact` and show other active sessions on the project.
+- `memory-boost init --example`: a small wiki with one finding of each drift kind and four
+  synthetic transcripts to try everything without your own data.
+
+For agents and maintainers:
+
+- CLI contract: 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.
+- `MEMORY_BOOST_TODAY` pins the date for reproducible reports.
+- Release pipeline: actions pinned to SHAs, minimal token permissions, PyPI Trusted Publishing
+  behind a manual approval; zizmor, pip-audit and bandit before every release.

memory_boost-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+In short: be kind, assume good faith, critique code rather than people.
+
+To report a problem privately, use the repository's Security tab ("Report a vulnerability"),
+which reaches the maintainer only, and say it is a conduct report. Reports are kept confidential.

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.0 → memory_boost-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memory-boost
-Version: 0.1.0
+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 -->
@@ -32,7 +34,7 @@ Description-Content-Type: text/markdown
 </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>
+  <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>
 
@@ -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.
@@ -171,23 +201,35 @@ 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)]
-```
+<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 `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
 
@@ -205,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 |
@@ -218,11 +260,11 @@ 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.
-- The wiki is read by your agents as instructions. Only use a wiki you trust; see [SECURITY.md](SECURITY.md).
+- The wiki is read by your agents as instructions. Only use a wiki you trust; see [SECURITY.md](https://github.com/arnaugonzalez/memory-boost/blob/main/SECURITY.md).
 
 ## License
 

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

@@ -10,7 +10,7 @@
 </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>
+  <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>
 
@@ -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.
@@ -149,23 +177,35 @@ 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)]
-```
+<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 `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
 
@@ -183,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 |
@@ -196,11 +236,11 @@ 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.
-- The wiki is read by your agents as instructions. Only use a wiki you trust; see [SECURITY.md](SECURITY.md).
+- The wiki is read by your agents as instructions. Only use a wiki you trust; see [SECURITY.md](https://github.com/arnaugonzalez/memory-boost/blob/main/SECURITY.md).
 
 ## License
 

memory_boost-0.2.0/docs/architecture.mmd

@@ -0,0 +1,11 @@
+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)]

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.0 → memory_boost-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memory-boost"
-version = "0.1.0"
+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"