fastrmemory 0.4.0 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "fastrmemory",
       "source": "./",
       "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
-      "version": "0.4.0"
+      "version": "0.6.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fastrmemory",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
   "author": {
     "name": "Fastrsoft"
@@ -12,7 +12,7 @@
   "mcpServers": {
     "fastrmemory": {
       "command": "npx",
-      "args": ["-y", "fastrmemory@0.4.0", "mcp"]
+      "args": ["-y", "fastrmemory@0.6.0", "mcp"]
     }
   }
 }

package/.cursor/mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "fastrmemory@0.3.1",
+        "fastrmemory@0.5.0",
         "mcp"
       ]
     }

package/.cursor/skills/fastr-setup/SKILL.md

@@ -14,7 +14,7 @@ allowed-tools: Bash(fastr *), Bash(fastrmemory *), Bash(npx -y fastrmemory*)
 ## 1. Project install (recommended)
 Run from the project root:
 ```bash
-npx -y fastrmemory@0.3.1 hook install
+npx -y fastrmemory@0.5.0 hook install
 ```
 This is idempotent and backs up files it changes. It writes:
 - `.mcp.json`: a project-scoped `fastrmemory` MCP server.
@@ -25,13 +25,13 @@ Commit `.mcp.json` and `.claude/settings.json` so the team shares the setup. Res
 
 ## 2. Manual MCP registration (alternative)
 ```bash
-claude mcp add fastrmemory -- npx -y fastrmemory@0.3.1 mcp
+claude mcp add fastrmemory -- npx -y fastrmemory@0.5.0 mcp
 ```
-On native Windows use `-- cmd /c npx -y fastrmemory@0.3.1 mcp`. Pass `--scope project` (before the name) to write `.mcp.json`. For a user-scoped registration (the default when `--scope project` is omitted), append `--project <absolute-project-path>` so the server does not use the client's launch directory; `fastr setup` writes that path automatically. This adds tools only, not hooks.
+On native Windows use `-- cmd /c npx -y fastrmemory@0.5.0 mcp`. Pass `--scope project` (before the name) to write `.mcp.json`. For a user-scoped registration (the default when `--scope project` is omitted), append `--project <absolute-project-path>` so the server does not use the client's launch directory; `fastr setup` writes that path automatically. This adds tools only, not hooks.
 
 ## 3. Verify
 ```bash
-npx -y fastrmemory@0.3.1 status
+npx -y fastrmemory@0.5.0 status
 claude mcp list
 ```
 `status` prints the project ID, memory counts, and database path (`.fastr/` under the project). Inside a session, call:

package/.cursor/skills/skills.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://skills.sh/schema/v1.json",
   "name": "fastrmemory-skills",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Agent Skills that teach coding agents when to recall, log traps, curate, and commit FastrMemory.",
   "author": "Fastrsoft",
   "license": "Apache-2.0",

package/README.md

@@ -10,11 +10,11 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%3E%3D22.16.0-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 [![Protocol](https://img.shields.io/badge/Protocol-MCP%20v2-7C3AED?style=flat-square)](https://modelcontextprotocol.io)
-[![Tests](https://img.shields.io/badge/Tests-293%20Passed-brightgreen?style=flat-square)](tests/)
+[![Tests](https://img.shields.io/badge/Tests-388%20Passed-brightgreen?style=flat-square)](tests/)
 [![MCP Setup](https://img.shields.io/badge/MCP%20Setup-fastr%20mcp%20init-7C3AED?style=flat-square)](#-one-click-agent-mcp-configuration)
 [![Architecture](https://img.shields.io/badge/Architecture-Zero--Daemon%20WAL-orange?style=flat-square)](#-architecture)
 
-> **Status (2026-10-23):** **`fastrmemory@0.3.1` is published and is `latest`; `0.4.0` is prepared on `main` and is not tagged or published.** Evidence for 0.3.1: `npm view fastrmemory version` -> `0.3.1`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.3.1"}`; tag `v0.3.1` (`3a3cac6`); published 2026-10-22 23:02 UTC via GitHub Actions OIDC with npm provenance; GitHub Release tarball SHA-256 `747f61791dcb7c5694f3cf5cc8705152892a5b16cb33bec51a356fc22112a7b8`; `npm install -g fastrmemory@0.3.1` + `fastr --version` -> `0.3.1`. Caveat: Node.js >=22.16.0; the npm README for 0.3.1 was rendered at the release tag and still labels 0.3.1 the release target; this post-release docs commit is not part of that render; `0.3.0` remains published historical. This release replaces the stale `0.3.0` npm README, fixes Windows MCP commands, pins user-scoped clients to the project root, and adds the Node runtime guard. The old scoped npm entries (`@atifjubaer/fastrmemory` and `fastrmemory@0.0.0-stage`) were removed on 2026-10-23; the GitHub `v0.2.1` tag and release remain as history. This README tracks current `main`; published release evidence remains **0.3.1**. Use the exact `0.3.1` version for reproducibility. `0.4.0` adds `fastr mcp init` and LF checkout enforcement; those changes are not in the published `0.3.1` tarball. Until `0.4.0` is published, `npx fastrmemory@latest mcp init` still resolves to `0.3.1` and does not include the command; use the source-checkout path in the MCP setup section. CI run `39879595191` at `098100e` (the 0.4.0 preparation commit) passed all six matrix jobs on 2026-10-23, including Windows Node `22.x` and `24.x`. The release post for 0.2.1 remains at [docs/blog/2026-10-21-fastrmemory-0.2.1.md](docs/blog/2026-10-21-fastrmemory-0.2.1.md). The exact release surface is in [CHANGELOG.md](CHANGELOG.md). The headline benchmark uses **240 deterministic synthetic cases with a 20% holdout**, not SWE-bench or LongMemEval. Public LongMemEval, LoCoMo, and self-repository retrieval-only results plus pinned external baselines are in [BENCHMARKS.md](BENCHMARKS.md); no QA-leaderboard parity is claimed. Performance, packaging, and retrieval claims are tracked in [CLAIMS.md](CLAIMS.md); every README section is mapped to claim IDs in the README claim trace at the end of that ledger. Methodology, caveats, and raw JSON are in [BENCHMARKS.md](BENCHMARKS.md).
+> **Status (2026-10-23):** **`fastrmemory@0.5.0` is published and is `latest`.** Evidence: `npm view fastrmemory version` -> `0.5.0`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.5.0"}`; tag `v0.5.0` (`54a79ab`); published 2026-10-23 15:20 UTC via GitHub Actions OIDC with npm provenance; release workflow run `39977196250` passed the full gate, clean tarball install, registry verification, and GitHub Release upload; GitHub Release tarball SHA-256 `10420ed6c70e6db52984ad6b895949f0f1d849dff06e2cb9227b7b56540cfb0e`; `npm install -g fastrmemory@0.5.0` + `fastr --version` -> `0.5.0`; `npm audit signatures` reports 5 verified registry signatures and 4 verified attestations. Caveat: Node.js >=22.16.0; `0.4.0` remains published historical, `0.3.1` remains published historical, and `0.3.0` remains historical. This release adds `fastr mcp init --source local`, with no schema migration. The old scoped npm entries (`@atifjubaer/fastrmemory` and `fastrmemory@0.0.0-stage`) were removed on 2026-10-23; the GitHub `v0.2.1` tag and release remain as history. This README tracks current `main`. Current `main` is **`0.5.0`** and has **388 tests / 61 files**; `--source local` is available from published `0.5.0`. Use the exact `0.5.0` version for reproducibility. CI run `39935705994` at `6c2a53a` passed all six matrix jobs on 2026-10-23, including Windows Node `22.x` and `24.x`; the `0.5.0` release commit `54a79ab` passed run `39977196250`, and the historical `0.4.0` release commit `bb365c2` passed run `39879913968`. The release post for 0.2.1 remains at [docs/blog/2026-10-21-fastrmemory-0.2.1.md](docs/blog/2026-10-21-fastrmemory-0.2.1.md). The exact release surface is in [CHANGELOG.md](CHANGELOG.md). The headline benchmark uses **240 deterministic synthetic cases with a 20% holdout**, not SWE-bench or LongMemEval. Public LongMemEval, LoCoMo, and self-repository retrieval-only results plus pinned external baselines are in [BENCHMARKS.md](BENCHMARKS.md); no QA-leaderboard parity is claimed. Performance, packaging, and retrieval claims are tracked in [CLAIMS.md](CLAIMS.md); every README section is mapped to claim IDs in the README claim trace at the end of that ledger. Methodology, caveats, and raw JSON are in [BENCHMARKS.md](BENCHMARKS.md).
 
 <p align="center">
   <a href="#-overview">Overview</a> &bull;
@@ -39,15 +39,15 @@
 
 | Claim | Current result | Evidence |
 |---|---|---|
-| Install path | Published `fastrmemory@0.3.1`; `0.4.0` prepared on `main`, not published | `npm view fastrmemory version` -> `0.3.1`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.3.1"}`; `npm install -g fastrmemory@0.3.1`; `fastr --version` -> `0.3.1`; GitHub Release tarball SHA-256 `747f6179...`; old scoped npm entries removed |
-| Synthetic retrieval | Holdout `95.8%` Hit@1, `100%` Hit@5, MRR `0.969` | `npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json` |
-| Test suite | `293` tests across `53` files on current HEAD; published `0.3.1` is `282` / `52`; v0.2.1 is `235` / `43` | `npm test` |
-| MCP setup (0.4.0 prepared) | `fastr mcp init` merges portable configs for 9 JSON clients and prints a Codex TOML snippet | `npm test -- tests/mcp-init.test.ts` -> `11 passed`; `fastr mcp init --client claude --dry-run` |
+| Install path | Published `fastrmemory@0.5.0` | `npm view fastrmemory version` -> `0.5.0`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.5.0"}`; `npm install -g fastrmemory@0.5.0`; `fastr --version` -> `0.5.0`; GitHub Release tarball SHA-256 `10420ed6...`; old scoped npm entries removed |
+| Synthetic retrieval (optional MiniLM) | Holdout `95.8%` Hit@1, `100%` Hit@5, MRR `0.969` | `npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json` |
+| Test suite | `354` tests across `59` files on current `main`; published `0.5.0` is `297` / `53`; historical `0.4.0` is `293` / `53`; `0.3.1` is `282` / `52`; v0.2.1 is `235` / `43` | `npm test`; `npm run check:ci` |
+| MCP setup | `fastr mcp init` merges portable registry configs or active-CLI local configs for 9 JSON clients and prints a Codex TOML snippet; `--source local` ships in published `0.5.0` | `npm test -- tests/mcp-init.test.ts` -> `15 passed`; `fastr mcp init --client claude --source local --dry-run --json` -> `node .../dist/bin/fastr.js mcp --project ...` |
 | Crash safety | 10/10 runs, 0 lost, 0 duplicate ids/titles | `npm run test:crash`; `bench/results/crash-test.json` |
 | Public retrieval (0.3.0) | LongMemEval `+10.4pp` / `+11.0pp` Hit@5; LoCoMo `+4.4pp` / `+2.3pp` (target missed) | [docs/EXTERNAL_BASELINE.md](docs/EXTERNAL_BASELINE.md) |
 | Release score | Provisional `9.4 / 10`; `9.2` target met; Retrieval remains Partial | [SCORECARD.md](SCORECARD.md) |
 
-The synthetic table is not SWE-bench or LongMemEval. Public numbers are retrieval-only and are not QA-leaderboard results. Full provenance is in [CLAIMS.md](CLAIMS.md).
+The synthetic table is not SWE-bench or LongMemEval. Public numbers are retrieval-only and are not QA-leaderboard results. The `95.8%` row uses optional MiniLM; the default offline hash path scores `77.1%` Hit@1 / `93.8%` Hit@5 on the same holdout. Full provenance is in [CLAIMS.md](CLAIMS.md).
 
 ---
 
@@ -77,7 +77,7 @@ Never deletes facts during consolidation (there is no destructive sleep step). R
 <td width="33%" align="center">
 
 ### 🎯 Triple-Stream RRF ($k=20$)
-Fuses FTS5 BM25 + optional local embeddings + file-graph links. Error traps receive a **conditional 2.0x boost** only for trap-intent or file-scoped queries, with per-ID outcome feedback (+0.2 / -0.5). Three consecutive bad outcomes move a memory to dormant; confidence tiers are `high`, `medium`, `low`, `dormant`, and `superseded`.
+Fuses FTS5 BM25 + optional local embeddings + file-graph links. Error traps receive a **conditional 2.0x boost** only for trap-intent or file-scoped queries, with per-ID outcome feedback (+0.2 / -0.5). Three consecutive bad outcomes move a memory to dormant; confidence tiers are `high`, `medium`, `low`, `dormant`, and `superseded`. Counting questions ("how many projects have I led?") additionally run an aggregate-coverage pass: a second lexical query over their content terms, fused with the original, returning up to 20 rows so the caller can count. `retrieval.temporalFilter` adds opt-in date windows ("past two weeks", "this year") parsed against the question date.
 
 </td>
 </tr>
@@ -110,42 +110,68 @@ Clients commonly used with FastrMemory include Codex CLI, Gemini CLI, OpenCode,
 
 ### ⚡ Run Without a Global Install
 
-The canonical package target is unscoped `fastrmemory@0.3.1`. `0.4.0` is prepared on `main` but is not published; keep using `0.3.1` for installs until the release workflow completes. The old scoped npm entries were removed on 2026-10-23.
+The canonical package target is unscoped `fastrmemory@0.5.0`. `0.4.0` and `0.3.1` remain published historical. The old scoped npm entries were removed on 2026-10-23.
 
 ```bash
 # Canonical one-shot (pins the exact release):
-npx -y fastrmemory@0.3.1 setup
+npx -y fastrmemory@0.5.0 setup
 
 # Or launch the local Web UI:
-npx -y fastrmemory@0.3.1 ui
+npx -y fastrmemory@0.5.0 ui
 ```
 
-The GitHub source path remains available for development only: `npx github:atifjubaer/fastrmemory setup`. For a reproducible source install, pin the tag: `npx github:atifjubaer/fastrmemory#v0.3.1 setup`. The current `main` contains the unpublished `0.4.0` source. Do not use either GitHub form in generated MCP or hook configs; those must use the npm package. The default `latest` channel tracks new releases, and `--channel pinned` records the exact version for reproducibility.
+The GitHub source path remains available for development only: `npx github:atifjubaer/fastrmemory setup`. For a reproducible source install, pin the tag: `npx github:atifjubaer/fastrmemory#v0.5.0 setup`. Do not use either GitHub form in generated MCP or hook configs; those must use the npm package. The default `latest` channel tracks new releases, and `--channel pinned` records the exact version for reproducibility.
 
 ---
 
 ### Install from npm
 
 ```bash
-# Canonical install (latest is 0.3.1):
+# Canonical install (latest is 0.5.0):
 npm install -g fastrmemory
 fastr --version
 
 # Exact release:
-npm install -g fastrmemory@0.3.1
+npm install -g fastrmemory@0.5.0
 ```
 
 For a one-shot run without a global install:
 
 ```bash
-npx -y fastrmemory@0.3.1 --version
+npx -y fastrmemory@0.5.0 --version
 ```
 
-`0.3.1` is built from tag `v0.3.1` by `.github/workflows/release.yml`, which runs the full gate, publishes with npm provenance, and attaches the same tarball to the GitHub Release. Verify the registry result with `npm view fastrmemory@0.3.1 version` and `npm view fastrmemory dist-tags --json`; a first E404 for a few minutes is registry propagation, not a failed publish. The old scoped npm entries remain removed. Do not republish `0.3.0`. `0.4.0` is prepared on `main`; no tag `v0.4.0` and no npm publication exist as of 2026-10-23.
+`0.5.0` is built from tag `v0.5.0` by `.github/workflows/release.yml`, which runs the full gate, publishes with npm provenance, and attaches the same tarball to the GitHub Release. Verify the registry result with `npm view fastrmemory@0.5.0 version` and `npm view fastrmemory dist-tags --json`; a first E404 for a few minutes is registry propagation, not a failed publish. The old scoped npm entries remain removed. Do not republish `0.3.0`. `0.4.0` and `0.3.1` remain published historical.
+
+### Update an Existing Install
+
+Stop every agent, hook, `fastr ui`, and `fastr daemon` before changing versions. Run this from the project root:
+
+```bash
+# 1. Back up memory before changing versions
+fastr backup fastr-backup.jsonl
+fastr backup --verify fastr-backup.jsonl
+
+# 2. Update the global CLI
+npm install -g fastrmemory@latest
+fastr --version
+
+# 3. Refresh project integration (choose what you use)
+fastr mcp init --client all --scope project   # portable npx configs only
+fastr mcp init --client all --scope user --source local --profile core  # installed CLI
+fastr setup                                   # MCP configs, AGENTS.md, and skills
+fastr hook install                            # lifecycle hooks plus MCP for hook clients
+
+# 4. Verify
+fastr status
+fastr hygiene
+```
+
+`0.5.0` has no schema migration. If you use `--channel pinned`, rerun `fastr mcp init` after each update; with the default `latest` channel, restart the client to pick up the new release. If you use `--source local`, the config points at the installed CLI, so updating the global package updates the server without rewriting the config. `fastr setup` refreshes copied skills, overwrites same-named skill files, removes retired skills, and leaves user-owned directories. `fastr hook install` does not copy skills. See [MIGRATION.md](MIGRATION.md) for rollback.
 
 ### One-Command MCP Setup
 
-`fastr mcp init` is the shadcn-style setup path. It is config-only: it merges the `fastrmemory` MCP entry into an existing client config, preserves unrelated keys, writes a one-time `.fastr.bak` backup, and is idempotent. It does not install lifecycle hooks, skills, or the OpenCode plugin; use `fastr hook install` for those.
+`fastr mcp init` is the shadcn-style setup path. It is config-only: it merges the `fastrmemory` MCP entry into an existing client config, preserves unrelated keys, writes a one-time `.fastr.bak` backup, and is idempotent. It does not install lifecycle hooks, skills, or the OpenCode plugin; use `fastr hook install` for hooks and the OpenCode plugin, and `fastr setup` for skills.
 
 ```bash
 # Claude Code (project-scoped .mcp.json)
@@ -175,31 +201,41 @@ yarn dlx fastrmemory@latest mcp init --client claude
 bunx fastrmemory@latest mcp init --client claude
 ```
 
-The default `--channel latest` writes `fastrmemory@latest`, so a client restart picks up the newest npm release. Use `--channel pinned` for a reproducible config containing the exact version that ran the command; on current `main` that writes `fastrmemory@0.4.0`, which is not installable from npm until the release publishes. `--runner pnpm|yarn|bunx` changes the generated runner, `--profile core` selects the 12-tool surface, `--dry-run` prints targets without writing, and `--scope user` writes user-level configs with an explicit `--project /absolute/path` so the server always opens the intended database. Codex prints a `[mcp_servers.fastrmemory]` TOML block for `~/.codex/config.toml` instead of rewriting a user-owned TOML file.
+The default `--channel latest` writes `fastrmemory@latest`, so a client restart picks up the newest npm release. Use `--channel pinned` for a reproducible config containing the exact version that ran the command; on current `main` that writes `fastrmemory@0.5.0`. `--runner pnpm|yarn|bunx` changes the generated runner, `--profile full` selects the 43-tool surface (the default is the 12-tool core profile), `--dry-run` prints targets without writing, and `--scope user` writes user-level configs with an explicit `--project /absolute/path` so the server always opens the intended database. Codex prints a `[mcp_servers.fastrmemory]` TOML block for `~/.codex/config.toml` instead of rewriting a user-owned TOML file.
+
+For a globally installed CLI, use `--source local` to write the active CLI path instead of an npx command. It always appends an absolute `--project`, so the config is machine-specific but starts without an npx cold start:
+
+```bash
+fastr mcp init --client all --scope user --source local --profile core
+```
+
+Updating the global package updates the server; rerun the command only if the CLI path changes. Use the default `--source registry` for portable project configs that are committed and shared across machines.
+
+> `--source local` ships in published `0.5.0`; `0.4.0` remains published historical. On `0.4.0`, use `fastr setup` for an installed-CLI config.
 
-> `mcp init` is prepared in `0.4.0` on `main`; `0.4.0` is not tagged or published as of 2026-10-23, and `npx fastrmemory@latest mcp init` still resolves to published `0.3.1`. Until `0.4.0` publishes, run the same commands from a source checkout (`npx --yes github:atifjubaer/fastrmemory#main mcp init ...`) or after `npm run build:core` with `node bin/fastr-guard.mjs mcp init ...`.
+> `mcp init` ships in `0.4.0` and later; `npx fastrmemory@latest mcp init ...` now resolves to published `0.5.0`. If you need the previous release, use `fastr setup` or pin `fastrmemory@0.3.1`.
 
 ### Install from GitHub
 
 For a one-shot source run, pin the release tag:
 
 ```bash
-npx --yes github:atifjubaer/fastrmemory#v0.3.1 --version
-npx --yes github:atifjubaer/fastrmemory#v0.3.1 setup
+npx --yes github:atifjubaer/fastrmemory#v0.5.0 --version
+npx --yes github:atifjubaer/fastrmemory#v0.5.0 setup
 ```
 
 For a global CLI without npm's Git resolver, download the release tarball:
 
 ```bash
-curl -L -o fastrmemory-0.3.1.tgz \
-  https://github.com/atifjubaer/fastrmemory/releases/download/v0.3.1/fastrmemory-0.3.1.tgz
-npm install -g ./fastrmemory-0.3.1.tgz
+curl -L -o fastrmemory-0.5.0.tgz \
+  https://github.com/atifjubaer/fastrmemory/releases/download/v0.5.0/fastrmemory-0.5.0.tgz
+npm install -g ./fastrmemory-0.5.0.tgz
 fastr --version
 ```
 
-On Windows, download the same URL with `Invoke-WebRequest` or a browser, then run `npm install -g .\fastrmemory-0.3.1.tgz`. For a local project install, use `npm install --no-save ./fastrmemory-0.3.1.tgz` instead of the global flag.
+On Windows, download the same URL with `Invoke-WebRequest` or a browser, then run `npm install -g .\fastrmemory-0.5.0.tgz`. For a local project install, use `npm install --no-save ./fastrmemory-0.5.0.tgz` instead of the global flag.
 
-> Git installs build from source and are slower than the npm tarball; for a global CLI, prefer the npm package or the release tarball above. `npm install -g git+https://...` is not recommended with npm 11 because the `prepare` build does not receive dev dependencies. Both `fastrmemory` and `fastr` (short alias) are executable after installation. The canonical package is unscoped `fastrmemory@0.3.1`; the old scoped npm entries are gone. Use npm for generated MCP and hook configs so installs stay reproducible.
+> Git installs build from source and are slower than the npm tarball; for a global CLI, prefer the npm package or the release tarball above. `npm install -g git+https://...` is not recommended with npm 11 because the `prepare` build does not receive dev dependencies. Both `fastrmemory` and `fastr` (short alias) are executable after installation. The canonical package is unscoped `fastrmemory@0.5.0`; the old scoped npm entries are gone. Use npm for generated MCP and hook configs so installs stay reproducible.
 
 ### 2. Verify Database Health
 
@@ -299,9 +335,10 @@ fastrmemory daemon start
 fastrmemory daemon status
 fastrmemory daemon stop
 
-# Auto-wire MCP configs, lifecycle hooks, and Planetary Skills into Claude Code, Cursor,
-# Gemini CLI, GitHub Copilot CLI, and OpenCode; setup also wires Antigravity, Claude Desktop, and Windsurf:
+# Auto-wire MCP + lifecycle hooks for Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode:
 fastrmemory hook install
+
+# Auto-wire MCP + AGENTS.md + Planetary Skills; setup also wires Antigravity, Claude Desktop, and Windsurf:
 fastrmemory setup
 
 # Mine past Git bug fixes directly into staging error traps:
@@ -336,17 +373,23 @@ fastrmemory vision search "modal error 401"
 
 # Pre-merge CI/CD gate checking PR diffs against active error traps:
 fastrmemory guard --strict
+
+# Optional 30 MB static semantic model (never downloaded implicitly):
+fastrmemory model status
+fastrmemory model install
 ```
 
 `fastrmemory hygiene` reports orphaned file links, conflict rows, and feedback rows; duplicate active memories by normalized title or exact content; and stale unpinned active memories (default 90 days since the last recall or creation). `npm run check:hygiene` runs the same inspector against a deterministic fixture inside `check:ci`; it does not mutate a project database. Use `--fail-on-issues` when a script should exit nonzero on findings.
 
+`fastrmemory model install` fetches `minishlab/potion-base-8M` (256-dim, 30,236,760 bytes), verifies both files against pinned SHA-256 hashes, and stores them under `~/.fastr/models/`. The tier is a bounded reranker over BM25 candidates: it fixes 1 case and breaks 1 across the 120-case LongMemEval slice, so it is documented as non-regressive, not as an accuracy win. Default recall is BM25-only until the asset is installed and backfill has produced vectors.
+
 ---
 
 ## 🔌 One-Click Agent MCP Configuration
 
-`fastr mcp init` is the one-command path for MCP-only wiring. It writes the platform-correct runner (`npx`, `pnpm dlx`, `yarn dlx`, or `bunx`; `cmd /c ...` on native Windows), preserves unrelated config keys, and is idempotent. `fastr setup` remains the full installer for `.fastr/`, `AGENTS.md`, skills, and lifecycle hooks; `fastr hook install` remains the hook-only path.
+`fastr mcp init` is the one-command path for MCP-only wiring. By default it uses `--source registry` and writes the platform-correct portable runner (`npx`, `pnpm dlx`, `yarn dlx`, or `bunx`; `cmd /c ...` on native Windows). Pass `--source local` to write the active CLI path plus an absolute `--project`, which is useful for a globally installed CLI but makes the config machine-specific. It preserves unrelated config keys and is idempotent. `fastr setup` remains the full installer for `.fastr/`, `AGENTS.md`, MCP configs, and skills; `fastr hook install` adds lifecycle hooks plus MCP configs for Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode.
 
-`fastr hook install` merges lifecycle hooks for Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, and OpenCode, and writes the OpenCode context/compaction plugin. Gemini CLI requires strict JSON on hook stdout; Copilot returns `permissionDecision: "ask"` for an active trap because it has no model-facing advisory field for `preToolUse`.
+`fastr hook install` merges lifecycle hooks for Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, and OpenCode, and writes the OpenCode context/compaction plugin. `fastr hook uninstall` removes exactly what install wrote — the `fastrmemory` MCP entry, the hook commands, the managed OpenCode plugin, and the `AGENTS.md` discipline block — while leaving every user entry in the same files untouched. Both commands are idempotent, accept `--client <ids|all>`, `--project <dir>`, `--no-agents-md`, and `--json`, and are covered by [docs/CLIENT_SUPPORT.md](docs/CLIENT_SUPPORT.md). Gemini CLI requires strict JSON on hook stdout; Copilot returns `permissionDecision: "ask"` for an active trap because it has no model-facing advisory field for `preToolUse`.
 
 | Client | Project config | User config | JSON key |
 | :--- | :--- | :--- | :--- |
@@ -376,17 +419,19 @@ Example POSIX project config generated by `fastr mcp init --client cursor` (Wind
 
 VS Code uses `servers` instead of `mcpServers`; OpenCode uses `mcp.servers` with a command array and `"type": "local"`. Existing `opencode.json(c)` settings are preserved, but a JSONC config is reported for manual wiring rather than rewritten. Codex is always printed as a `[mcp_servers.fastrmemory]` TOML block because rewriting a user-owned TOML file safely requires a dedicated parser.
 
-For user-scoped clients, the generated entry includes `--project /absolute/path/to/repo`; this prevents the client's launch directory from selecting the wrong database. `fastr setup` also writes the absolute `node` path and is the recommended path when the client cannot launch package-runner shims. On native Windows, `fastr mcp init` automatically emits `"command": "cmd"` with `"/c"` and the runner, so manual `npx.cmd` fixes are not needed.
+For user-scoped clients, the generated entry includes `--project /absolute/path/to/repo`; this prevents the client's launch directory from selecting the wrong database. `fastr setup` also writes the absolute `node` path and is the recommended path when the client cannot launch package-runner shims. `--source local` is the `mcp init` equivalent for an installed CLI: it writes the active CLI path and an absolute `--project`; use `--source registry` (the default) when the config will be committed or shared. `--source local` ships in published `0.5.0`; on `0.4.0`, use `fastr setup` for an installed-CLI config. On native Windows, `fastr mcp init` automatically emits `"command": "cmd"` with `"/c"` and the runner, so manual `npx.cmd` fixes are not needed.
+
+`--client all --scope project` covers the six project-scoped clients in the table. `--client all --scope user` covers the eight user-scoped clients; OpenCode and Copilot CLI are project-only, while Codex prints a TOML block for manual insertion. User-scoped entries pin one `--project` database, so use project scope when each developer may open a different checkout.
 
 ---
 
 ## 🛠️ MCP Server: Tools & Resources
 
-Built using the official **v2 `@modelcontextprotocol/server`** SDK. The tool list below describes **0.4.0** (prepared; unchanged from 0.3.1); the v0.2.1 release has 4 resources.
+Built using the official **v2 `@modelcontextprotocol/server`** SDK. The tool list below describes **0.5.0** (tool surface unchanged from 0.4.0); the v0.2.1 release has 4 resources.
 
-### 41 MCP Tools
+### 43 MCP Tools
 
-The default **full profile** exposes all 41 tools. For a smaller schema, start the **core profile** with `fastrmemory mcp --profile core` or `FASTR_MCP_PROFILE=core`; it exposes the 12-tool daily loop: `fastr_recall`, `fastr_remember`, `fastr_handoff`, `fastr_trap_recall`, `fastr_trap_log`, `fastr_status`, `fastr_get`, `fastr_timeline`, `fastr_diff`, `fastr_replay`, `fastr_compress`, and `fastr_diagnose`. Resources and prompts are the same in both profiles. Pass `--project /absolute/path/to/repo` when the host starts the server outside the repository, so memory is written to the intended `.fastr/fastr.db`.
+The default **core profile** exposes 12 tools: the daily loop (`fastr_recall`, `fastr_remember`, `fastr_handoff`, `fastr_trap_recall`, `fastr_trap_log`, `fastr_status`, `fastr_get`, `fastr_replay`, `fastr_compress`, `fastr_diagnose`) plus `fastr_tools` for discovery and `fastr_call` for dispatch. Its `tools/list` payload is 8,715 bytes (~2,179 tokens). The **full profile** exposes all 43 tools; start it with `fastrmemory mcp --profile full` or `FASTR_MCP_PROFILE=full`. Every full-profile tool stays reachable from the core profile through `fastr_call`. Resources and prompts are the same in both profiles. Pass `--project /absolute/path/to/repo` when the host starts the server outside the repository, so memory is written to the intended `.fastr/fastr.db`.
 
 #### Cognitive Retrieval & Memory Core
 1. `fastr_recall`: Triple-stream hybrid search (BM25 + Vector + Spreading Activation Graph) with progressive L0–L3 token budgeting and air-gapped offline vector fallback.
@@ -449,6 +494,10 @@ The default **full profile** exposes all 41 tools. For a smaller schema, start t
 40. `fastr_vision_tag`: Tags screenshots, UI diagrams, and wireframes with OCR and semantic descriptions with 384-dim embeddings.
 41. `fastr_vision_search`: Hybrid vector and keyword search across stored visual assets for multimodal coding agents.
 
+#### Tool Discovery & Dispatch
+42. `fastr_tools`: Lists every tool the server can run, with its JSON input schema, filtered by name or description. Part of the core profile.
+43. `fastr_call`: Runs any tool from `fastr_tools` by name after validating arguments against that tool's schema. Part of the core profile.
+
 ### 2 MCP Prompt Templates
 
 - `pre-edit-check`: Given file paths, instructs the agent to check traps and relevant rules before editing.
@@ -516,6 +565,8 @@ FastrMemory ships 10 Agent Skills (in `skills/`, mirrored to `.cursor/skills/`)
 
 Run `npm run check:skills` to validate every tool call in the skills against `src/mcp/server.ts`.
 
+After updating the CLI, re-run `fastr setup` to refresh the copied skills. The installer overwrites same-named skill files, removes retired skills, and leaves unrelated user-owned directories. `fastr hook install` does not copy skills. Restart the client after setup. If you install the Claude Code plugin instead, update the plugin rather than maintaining a second copied skill set.
+
 ---
 
 ## 🏗️ Architecture
@@ -545,7 +596,7 @@ flowchart TD
 
     subgraph Protocol["4. Official MCP Protocol"]
         Budget --> MCPServer["Official MCP v2 Server\n(@modelcontextprotocol/server)"]
-        MCPServer --> Tools["41 tools • 2 prompts • 5 resources"]
+        MCPServer --> Tools["43 tools • 2 prompts • 5 resources"]
         Tools --> Agent
     end
 ```
@@ -560,7 +611,7 @@ Run the comprehensive unit test suite:
 npm test
 ```
 
-All **293 tests pass** across **53 test files** on current HEAD (`0.4.0` prepared); published `0.3.1` has **282 tests / 52 files**, and v0.2.1 has **235 tests / 43 files**. Coverage includes database schema, WAL locking, offline spooling, bi-temporal supersession, secret scrubbing, two-zone rendering, automated benchmarks, snapshots/rollback, branch merge conflict reports, replay/diff, memory envelopes, confidence tiers and 3-bad dormancy, memory hygiene checks, Memory CI, conflict-aware recall, portable backup manifests and verified restore, local rule import, OpenCode V2, Gemini CLI, and Copilot CLI wiring, git-learner, cognitive blame, commit synthesis, hybrid background daemon, token compression, self-healing doctor, multimodal vision, web dashboard server, pre-merge trap guardian, UI loopback security boundaries, atomic installer configuration safety, and shadcn-style `mcp init` client config merges.
+All **388 tests pass** across **61 test files** on current `main`; published `0.5.0` has **297 tests / 53 files**, historical `0.4.0` has **293 tests / 53 files**, `0.3.1` has **282 / 52**, and v0.2.1 has **235 / 43**. Coverage includes database schema, WAL locking, offline spooling, bi-temporal supersession, secret scrubbing, two-zone rendering, automated benchmarks, snapshots/rollback, branch merge conflict reports, replay/diff, memory envelopes, confidence tiers and 3-bad dormancy, memory hygiene checks, Memory CI, conflict-aware recall, portable backup manifests and verified restore, local rule import, OpenCode V2, Gemini CLI, and Copilot CLI wiring, git-learner, cognitive blame, commit synthesis, hybrid background daemon, token compression, self-healing doctor, multimodal vision, web dashboard server, pre-merge trap guardian, UI loopback security boundaries, atomic installer configuration safety, and shadcn-style `mcp init` client config merges, including local-source entries.
 
 **CI performance gates:** `check:query-plans`, `check:recall-latency`, and `check:install-size` run inside `check:ci`. CI executes them on the canonical Ubuntu/Node 24 job; other matrix jobs set `FASTR_PERF_GATE=0` because timing is runner-sensitive, while functional tests still run on every matrix entry.
 

package/dist/bin/fastr.js

@@ -9,8 +9,9 @@ import { scrubSecrets } from '../src/privacy/scrubber.js';
 import { runInteractiveSetup } from '../src/installer/setup.js';
 import { formatBenchmarkMarkdown } from '../src/bench/benchmark.js';
 import { startUiServer } from '../src/ui/server.js';
-import { installAgentHooks } from '../src/installer/hooks.js';
-import { formatMcpInitResult, initMcpClients, parseMcpChannel, parseMcpClients, parseMcpProfile, parseMcpRunner, parseMcpScope, } from '../src/installer/mcp-init.js';
+import { installHookClients, parseHookClients, uninstallHookClients } from '../src/installer/hooks.js';
+import { installStaticModel, removeStaticModel, staticModelStatus } from '../src/search/static-model-install.js';
+import { formatMcpInitResult, initMcpClients, parseMcpChannel, parseMcpClients, parseMcpProfile, parseMcpRunner, parseMcpScope, parseMcpSource, } from '../src/installer/mcp-init.js';
 import { learnFromGitHistory } from '../src/learn/git-learner.js';
 import { exportToObsidianVault } from '../src/export/obsidian.js';
 import { runLifecycleHook, toClaudeHookStdout, toGeminiHookStdout, toCopilotHookStdout } from '../src/hooks/runner.js';
@@ -68,7 +69,7 @@ program
 const mcpCmd = program
     .command('mcp')
     .description('Run FastrMemory as an MCP stdio server')
-    .option('--profile <profile>', 'Tool surface: full (default) or core (12 tools)')
+    .option('--profile <profile>', 'Tool surface: core (default, 12 tools) or full')
     .option('--project <path>', 'Project root for memory storage (defaults to cwd)')
     .action(async (options) => {
     try {
@@ -86,7 +87,8 @@ mcpCmd
     .option('--scope <scope>', 'project or user', 'project')
     .option('--channel <channel>', 'latest (auto-update) or pinned (exact version)', 'latest')
     .option('--runner <runner>', 'npx, pnpm, yarn, or bunx', 'npx')
-    .option('--profile <profile>', 'Tool surface: full or core', 'full')
+    .option('--profile <profile>', 'Tool surface: core (default, 12 tools) or full', 'core')
+    .option('--source <source>', 'registry (portable npx) or local (active CLI)', 'registry')
     .option('--project <path>', 'Project root for user-scoped configs', process.cwd())
     .option('--dry-run', 'Print the target files without writing', false)
     .option('--json', 'Print a machine-readable result', false)
@@ -96,7 +98,10 @@ Examples:
   $ fastrmemory mcp init --client cursor,vscode --channel pinned
   $ fastrmemory mcp init --client opencode --runner pnpm
   $ fastrmemory mcp init --client all --scope project
-  $ fastrmemory mcp init --client codex --scope user`)
+  $ fastrmemory mcp init --client all --scope user --source local --profile core
+  $ fastrmemory mcp init --client codex --scope user
+
+--source local writes the active CLI and an absolute --project; project configs are machine-specific.`)
     .action((options) => {
     try {
         const scope = parseMcpScope(options.scope);
@@ -104,6 +109,7 @@ Examples:
         const channel = parseMcpChannel(options.channel);
         const runner = parseMcpRunner(options.runner);
         const profile = parseMcpProfile(options.profile);
+        const source = parseMcpSource(options.source);
         const results = initMcpClients({
             clients,
             scope,
@@ -111,10 +117,11 @@ Examples:
             channel,
             runner,
             profile,
+            source,
             dryRun: options.dryRun,
         });
         if (options.json) {
-            console.log(JSON.stringify({ scope, channel, runner, profile, results }, null, 2));
+            console.log(JSON.stringify({ scope, channel, runner, profile, source, results }, null, 2));
             return;
         }
         for (const result of results) {
@@ -737,15 +744,51 @@ program
 const hookCmd = program.command('hook').description('Autonomous agent lifecycle hook management');
 hookCmd
     .command('install')
-    .description('Install FastrMemory MCP and hooks into Claude Code, Cursor, Gemini CLI, Copilot CLI, OpenCode, and AGENTS.md')
-    .action(() => {
-    const ctx = createFastrServerContext();
-    const res = installAgentHooks(ctx.config.projectRoot);
-    console.log(`\n=== FastrMemory Autonomous Hook Installation ===`);
-    for (const d of res.details) {
-        console.log(`- ${d}`);
+    .description('Install FastrMemory MCP and hooks into Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode')
+    .option('--client <clients>', 'Comma-separated client ids, or all', 'all')
+    .option('--project <path>', 'Project root (defaults to the current directory)')
+    .option('--no-agents-md', 'Do not touch AGENTS.md')
+    .option('--json', 'Print a machine-readable result', false)
+    .action((opts) => {
+    const projectRoot = path.resolve(opts.project ?? process.cwd());
+    const clients = parseHookClients(opts.client);
+    const res = installHookClients(projectRoot, clients, { agentsMd: opts.agentsMd });
+    if (opts.json) {
+        console.log(JSON.stringify({ projectRoot, clients: res.clients, agentsMdUpdated: res.agentsMdUpdated }, null, 2));
+    }
+    else {
+        console.log(`\n=== FastrMemory Autonomous Hook Installation ===`);
+        console.log(`Project: ${projectRoot}`);
+        for (const d of res.details)
+            console.log(`- ${d}`);
+        console.log(`\nAgent autonomous discipline active.\n`);
+    }
+    if (res.clients.some((client) => client.status === 'error'))
+        process.exitCode = 1;
+});
+hookCmd
+    .command('uninstall')
+    .description('Remove the FastrMemory MCP entries, hooks, OpenCode plugin, and AGENTS.md block this installer added')
+    .option('--client <clients>', 'Comma-separated client ids, or all', 'all')
+    .option('--project <path>', 'Project root (defaults to the current directory)')
+    .option('--no-agents-md', 'Do not touch AGENTS.md')
+    .option('--json', 'Print a machine-readable result', false)
+    .action((opts) => {
+    const projectRoot = path.resolve(opts.project ?? process.cwd());
+    const clients = parseHookClients(opts.client);
+    const res = uninstallHookClients(projectRoot, clients, { agentsMd: opts.agentsMd });
+    if (opts.json) {
+        console.log(JSON.stringify({ projectRoot, changed: res.changed, clients: res.clients, agentsMdRemoved: res.agentsMdRemoved }, null, 2));
+    }
+    else {
+        console.log(`\n=== FastrMemory Hook Removal ===`);
+        console.log(`Project: ${projectRoot}`);
+        for (const d of res.details)
+            console.log(`- ${d}`);
+        console.log(res.changed ? `\nFastrMemory integration removed.\n` : `\nNothing to remove.\n`);
     }
-    console.log(`\nAgent autonomous discipline active.\n`);
+    if (res.clients.some((client) => client.status === 'error'))
+        process.exitCode = 1;
 });
 hookCmd
     .command('run <event>')
@@ -1027,10 +1070,17 @@ program
 // 18. Diagnose command
 program
     .command('diagnose')
+    .alias('doctor')
     .description('Run deep health check across SQLite, FTS5 indices, file links, and task DAGs')
-    .action(() => {
+    .option('--drain-conflicts', 'Drain the deferred conflict queue before reporting', false)
+    .action((opts = {}) => {
     try {
         const ctx = createFastrServerContext();
+        if (opts.drainConflicts) {
+            const drained = healDatabase(ctx.db, ctx.config.projectId, { drainConflicts: true });
+            console.log(`\nDrained ${drained.conflictsDrained ?? 0} queued conflict check(s); recorded ${drained.conflictsCreated ?? 0} conflict(s); ` +
+                `extracted entities for ${drained.entitiesDrained ?? 0} memory(ies).`);
+        }
         const report = diagnoseDatabase(ctx.db, ctx.config.projectId);
         console.log(`\n=== FastrMemory Health Diagnostic ===`);
         console.log(`Status:    ${report.healthy ? '✅ HEALTHY' : '⚠️ ISSUES DETECTED'}`);
@@ -1039,6 +1089,8 @@ program
         console.log(`FTS5 Rows: ${report.metrics.ftsRowCount}`);
         console.log(`Links:     ${report.metrics.fileLinkCount}`);
         console.log(`Actions:   ${report.metrics.actionCount}`);
+        console.log(`Conflicts: ${report.metrics.pendingConflicts} queued`);
+        console.log(`FTS queue: ${report.metrics.pendingFts} pending`);
         console.log(`Mode:      ${report.metrics.walMode}`);
         if (report.issues.length > 0) {
             console.log(`\nIssues List:`);
@@ -1109,16 +1161,32 @@ program
 // 19. Heal command
 program
     .command('heal')
-    .description('Auto-repair database indices, orphaned file links, and WAL fragmentation')
+    .description('Auto-repair database indices, orphaned file links, WAL fragmentation, and the deferred conflict queue')
     .option('-d, --dry-run', 'Preview repairs without modifying database', false)
+    .option('--drain-conflicts', 'Run every queued deferred conflict check now', false)
+    .option('--conflict-batch-size <n>', 'Conflict queue rows per transaction', '20')
     .action((opts) => {
     try {
         const ctx = createFastrServerContext();
-        const res = healDatabase(ctx.db, ctx.config.projectId, { dryRun: opts.dryRun });
+        const batchSize = Number.parseInt(opts.conflictBatchSize, 10);
+        const res = healDatabase(ctx.db, ctx.config.projectId, {
+            dryRun: opts.dryRun,
+            drainConflicts: opts.drainConflicts,
+            conflictBatchSize: Number.isFinite(batchSize) && batchSize > 0 ? batchSize : 20
+        });
         console.log(`\n=== FastrMemory Self-Healing Doctor ===`);
         console.log(`Mode:      ${res.dryRun ? '🔍 DRY RUN' : '⚡ LIVE REPAIR'}`);
         console.log(`Fixed:     ${res.fixedCount} issue(s)`);
         console.log(`Remaining: ${res.remainingIssues} issue(s)`);
+        if (res.conflictsDrained !== undefined) {
+            console.log(`Conflicts: drained ${res.conflictsDrained} queued check(s), recorded ${res.conflictsCreated ?? 0}`);
+        }
+        if (res.entitiesDrained !== undefined) {
+            console.log(`Entities:  extracted for ${res.entitiesDrained} queued memory(ies)`);
+        }
+        if (res.ftsDrained !== undefined) {
+            console.log(`FTS index: ${res.ftsDrained} queued row(s) indexed`);
+        }
         if (res.actionsTaken.length > 0) {
             console.log(`\nActions:`);
             for (const a of res.actionsTaken) {
@@ -1226,5 +1294,51 @@ program
         process.exit(1);
     }
 });
+// 22. Optional static semantic model (30 MB, never downloaded implicitly)
+const modelCmd = program
+    .command('model')
+    .description('Manage the optional static semantic model (30 MB, opt-in)');
+modelCmd
+    .command('status')
+    .description('Show whether the static semantic model is installed')
+    .action(() => {
+    const status = staticModelStatus();
+    console.log(`Static model: ${status.installed ? 'installed' : 'not installed'}`);
+    console.log(`Directory:    ${status.dir}`);
+    if (status.installed) {
+        console.log(`Size:         ${(status.bytes / 1_000_000).toFixed(1)} MB`);
+        console.log(`Vector mode:  semantic (model id 3, 256-dim)`);
+    }
+    else {
+        console.log(`Missing:      ${status.missing.join(', ')}`);
+        console.log(`Install with: fastr model install`);
+    }
+});
+modelCmd
+    .command('install')
+    .description('Download and verify the static semantic model')
+    .option('-f, --force', 'Re-download even when a verified copy exists', false)
+    .action(async (opts) => {
+    try {
+        const result = await installStaticModel({
+            force: opts.force,
+            onProgress: (message) => console.log(message)
+        });
+        console.log(result.alreadyPresent
+            ? `\nModel already present in ${result.dir}`
+            : `\nInstalled to ${result.dir}`);
+        console.log('Recall now uses the semantic tier automatically when vectors exist.');
+    }
+    catch (err) {
+        console.error(`Model install failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+modelCmd
+    .command('remove')
+    .description('Delete the installed static semantic model')
+    .action(() => {
+    console.log(removeStaticModel() ? 'Static model removed.' : 'Static model is not installed.');
+});
 program.parse(process.argv);
 //# sourceMappingURL=fastr.js.map