fastrmemory 0.3.1 → 0.5.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.3.1"
+      "version": "0.5.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fastrmemory",
-  "version": "0.3.1",
+  "version": "0.5.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.3.1", "mcp"]
+      "args": ["-y", "fastrmemory@0.5.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.3.1",
+  "version": "0.5.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-282%20Passed-brightgreen?style=flat-square)](tests/)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
+[![Tests](https://img.shields.io/badge/Tests-297%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):** The canonical release target is **`fastrmemory@0.3.1`**. The release workflow publishes it with npm provenance and a matching GitHub Release tarball; verify with `npm view fastrmemory version` and require `latest` to be `0.3.1`. 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 **0.3.1**. Use the exact `0.3.1` version for reproducibility. 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.4.0` is published and is `latest`.** Evidence: `npm view fastrmemory version` -> `0.4.0`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.4.0"}`; tag `v0.4.0` (`bb365c2`); published 2026-10-23 07:32 UTC via GitHub Actions OIDC with npm provenance; release workflow run `39918288792` passed the full gate, clean tarball install, registry verification, and GitHub Release upload; GitHub Release tarball SHA-256 `b784e3e12b8a50deaee3b38dbc1f45c756bc37462f2d40433fdda5288cf554ad`; `npm install -g fastrmemory@0.4.0` + `fastr --version` -> `0.4.0`; `npm audit signatures` reports 5 verified registry signatures and 4 verified attestations. Caveat: Node.js >=22.16.0; `0.3.1` remains published historical and `0.3.0` remains historical. This release adds `fastr mcp init` and LF checkout enforcement, 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 adds `fastr mcp init --source local`; it has **297 tests / 53 files**. `0.5.0` is prepared but not yet published, so `--source local` remains unavailable from npm `latest` until the `v0.5.0` release workflow completes. Until then, use the exact `0.4.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.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;
@@ -23,13 +23,12 @@
   <a href="#-local-web-dashboard">Web UI</a> &bull;
   <a href="#-works-with-mcp--and-http-compatible-agents">Supported Agents</a> &bull;
   <a href="#-quick-start">Quick Start</a> &bull;
+  <a href="#-one-click-agent-mcp-configuration">MCP Setup</a> &bull;
   <a href="#-mcp-server-tools--resources">MCP Tools</a> &bull;
   <a href="#-architecture">Architecture</a> &bull;
-  <a href="ROADMAP.md">Roadmap</a> &bull;
   <a href="MIGRATION.md">Migration</a> &bull;
   <a href="SECURITY.md">Security</a> &bull;
-  <a href="SCORECARD.md">Scorecard</a> &bull;
-  <a href="#-contributing">Contributing</a>
+  <a href="SCORECARD.md">Scorecard</a>
 </p>
 
 </div>
@@ -40,14 +39,15 @@
 
 | Claim | Current result | Evidence |
 |---|---|---|
-| Install path | Canonical release target `fastrmemory@0.3.1`; old scoped npm entries removed | `npm view fastrmemory version` -> `0.3.1`; `npm install -g fastrmemory@0.3.1`; `fastr --version` -> `0.3.1` |
-| 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 | `282` tests across `52` files in `0.3.1`; v0.2.1 is `235` / `43` | `npm test` |
+| Install path | Published `fastrmemory@0.4.0` | `npm view fastrmemory version` -> `0.4.0`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.4.0"}`; `npm install -g fastrmemory@0.4.0`; `fastr --version` -> `0.4.0`; GitHub Release tarball SHA-256 `b784e3e1...`; 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 | `297` tests across `53` files on current `main` (`0.5.0`); published `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 `0.5.0` (prepared; `0.4.0` remains published until `v0.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).
 
 ---
 
@@ -110,60 +110,132 @@ 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`. The old scoped npm entries were removed on 2026-10-23.
+The canonical package target is unscoped `fastrmemory@0.4.0`. `0.3.1` remains 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.4.0 setup
 
 # Or launch the local Web UI:
-npx -y fastrmemory@0.3.1 ui
+npx -y fastrmemory@0.4.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`. Do not use either GitHub form in generated MCP or hook configs; those must pin the npm package version.
+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.4.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.4.0):
 npm install -g fastrmemory
 fastr --version
 
 # Exact release:
-npm install -g fastrmemory@0.3.1
+npm install -g fastrmemory@0.4.0
 ```
 
 For a one-shot run without a global install:
 
 ```bash
-npx -y fastrmemory@0.3.1 --version
+npx -y fastrmemory@0.4.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 built from tag `v0.4.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.4.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.3.1` remains 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 hooks and the OpenCode plugin, and `fastr setup` for skills.
+
+```bash
+# Claude Code (project-scoped .mcp.json)
+npx -y fastrmemory@latest mcp init --client claude
+
+# Cursor
+npx -y fastrmemory@latest mcp init --client cursor
+
+# VS Code (.vscode/mcp.json)
+npx -y fastrmemory@latest mcp init --client vscode
+
+# OpenCode (opencode.json)
+npx -y fastrmemory@latest mcp init --client opencode
+
+# Gemini CLI and GitHub Copilot CLI
+npx -y fastrmemory@latest mcp init --client gemini,copilot
+
+# Every project-scoped client at once
+npx -y fastrmemory@latest mcp init --client all --scope project
+```
+
+The same command through the other package runners:
+
+```bash
+pnpm dlx fastrmemory@latest mcp init --client claude
+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.5.0` (pending publication). `--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.
+
+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 `0.5.0`. Until the `v0.5.0` release workflow completes, published `0.4.0` remains the install target; use `fastr setup` on `0.4.0` for an installed-CLI config.
+
+> `mcp init` ships in `0.4.0`; `npx fastrmemory@latest mcp init ...` now resolves to published `0.4.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.4.0 --version
+npx --yes github:atifjubaer/fastrmemory#v0.4.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.4.0.tgz \
+  https://github.com/atifjubaer/fastrmemory/releases/download/v0.4.0/fastrmemory-0.4.0.tgz
+npm install -g ./fastrmemory-0.4.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.4.0.tgz`. For a local project install, use `npm install --no-save ./fastrmemory-0.4.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.4.0`; the old scoped npm entries are gone. Use npm for generated MCP and hook configs so installs stay reproducible.
 
 ### 2. Verify Database Health
 
@@ -263,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:
@@ -308,84 +381,47 @@ fastrmemory guard --strict
 
 ## 🔌 One-Click Agent MCP Configuration
 
-Use the installer when possible. `fastr setup` writes the platform-correct command (`node` with an absolute CLI path, or `cmd /c npx` where needed) and pins user-scoped clients to the project root. `fastr hook install` writes project-scoped configs and lifecycle hooks. The manual snippets below use `npx` for project-scoped clients; for user-scoped clients (Claude Desktop, Antigravity, Windsurf, and the Claude Code entry in `~/.claude.json`), append `--project /absolute/path/to/repo`.
+`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.
 
-### Claude Code (`~/.claude.json`, user-scoped)
-```json
-{
-  "mcpServers": {
-    "fastrmemory": {
-      "command": "npx",
-      "args": ["-y", "fastrmemory@0.3.1", "mcp", "--project", "/absolute/path/to/your/repo"]
-    }
-  }
-}
-```
+`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`.
 
-### Cursor (`.cursor/mcp.json`, project-scoped)
-```json
-{
-  "mcpServers": {
-    "fastrmemory": {
-      "command": "npx",
-      "args": ["-y", "fastrmemory@0.3.1", "mcp"]
-    }
-  }
-}
-```
-
-### Gemini CLI (`.gemini/settings.json`, project-scoped, 0.3.0)
-```json
-{
-  "mcpServers": {
-    "fastrmemory": {
-      "command": "npx",
-      "args": ["-y", "fastrmemory@0.3.1", "mcp"]
-    }
-  }
-}
-```
+| Client | Project config | User config | JSON key |
+| :--- | :--- | :--- | :--- |
+| Claude Code | `.mcp.json` | `~/.claude.json` | `mcpServers` |
+| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` | `mcpServers` |
+| VS Code | `.vscode/mcp.json` | VS Code `User/mcp.json` | `servers` |
+| OpenCode | `opencode.json` | project only | `mcp.servers` |
+| Gemini CLI | `.gemini/settings.json` | `~/.gemini/settings.json` | `mcpServers` |
+| GitHub Copilot CLI | `.github/mcp.json` | project only | `mcpServers` |
+| Windsurf | user only | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
+| Antigravity | user only | `~/.gemini/antigravity/mcp_config.json` | `mcpServers` |
+| Claude Desktop | user only | platform-specific | `mcpServers` |
+| Codex | user only | `~/.codex/config.toml` | printed TOML |
 
-`fastrmemory hook install` also merges `SessionStart`, `BeforeTool` (`write_file|replace`), `PreCompress`, and `SessionEnd` hooks into the same project settings file. Gemini CLI requires strict JSON on hook stdout, so the generated commands pass `--format gemini`. Google is transitioning users from Gemini CLI to Antigravity CLI; this integration targets the still-documented `.gemini/settings.json` contract.
+Example POSIX project config generated by `fastr mcp init --client cursor` (Windows uses `cmd /c npx ...`):
 
-### GitHub Copilot CLI (`.github/mcp.json`, project-scoped, 0.3.0)
 ```json
 {
   "mcpServers": {
     "fastrmemory": {
-      "type": "local",
       "command": "npx",
-      "args": ["-y", "fastrmemory@0.3.1", "mcp"]
+      "args": ["-y", "fastrmemory@latest", "mcp"]
     }
   }
 }
 ```
 
-`fastrmemory hook install` also merges `.github/hooks/fastrmemory.json` with `sessionStart`, `preToolUse` (`edit|create|str_replace_editor|apply_patch`), `preCompact`, and `sessionEnd` hooks. Copilot has no model-facing advisory field for `preToolUse`, so an active trap returns `permissionDecision: "ask"` with the warning; autopilot/non-interactive mode treats `ask` as deny. The shared `AGENTS.md` written by the installer supplies repository instructions.
+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.
 
-### OpenCode V2 (`opencode.json`, project-scoped, 0.3.0)
-```json
-{
-  "mcp": {
-    "servers": {
-      "fastrmemory": {
-        "type": "local",
-        "command": ["npx", "-y", "fastrmemory@0.3.1", "mcp"]
-      }
-    }
-  }
-}
-```
-
-`fastrmemory hook install` also writes `.opencode/plugins/fastrmemory/index.ts`, which injects the session-start handoff and critical rules into model context and captures a snapshot before compaction. Existing `opencode.json(c)` settings are preserved; JSONC configs are left untouched and reported for manual wiring.
+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 `0.5.0`; on published `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.
 
-> **Native Windows:** clients that cannot launch the `npx.cmd` shim directly should use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "fastrmemory@0.3.1", "mcp"]` (add `--project` for user-scoped clients). `fastr setup` writes the absolute `node` path automatically and is the recommended path.
+`--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.3.1** (unchanged from 0.3.0); 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
 
@@ -519,6 +555,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
@@ -563,7 +601,7 @@ Run the comprehensive unit test suite:
 npm test
 ```
 
-All **282 tests pass** across **52 test files** in 0.3.1 (the v0.2.1 release has **235 tests / 43 files**) covering 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, and atomic installer configuration safety.
+All **297 tests pass** across **53 test files** on current `main` (`0.5.0`); published `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.
 
@@ -640,88 +678,6 @@ cursor --install-extension fastrmemory-vscode-0.1.0.vsix
 
 ---
 
-## 🤝 Contributing & Pull Request Roadmap
-
-We warmly welcome contributions from the open-source community! Whether you are adding a new AI coding agent hook, integrating local embedding backends, or crafting 3D visualizations, your pull requests are valued and reviewed promptly.
-
-### 🏆 Contributor Wall of Fame
-
-Special thanks to **[@the-arizul](https://github.com/the-arizul)** for architecting PRs #1 through #11:
-- **PR #1**: Loopback security boundaries, DNS rebinding lockdown, and `dist-ui` package resolution.
-- **PR #2**: Safe atomic JSON config merges, nested Claude Code hook schemas, and sandboxed installer tests.
-- **PR #3**: Hardened GitHub Actions fork PR comment safety.
-- **PR #4**: Core SQLite B-tree heal, BUSY spool fallback, ATTACH injection prevention, and atomic claim/supersede.
-- **PR #5**: Git security hardening (zero shell interpolation, confined paths, and high-entropy secret scrubbing).
-- **PR #6**: Triple-stream RRF recall ranking calibration, zero irrelevant results, and Unicode query normalization.
-- **PR #7**: MCP server hardening (`isError` handling, bounded inputs, parameter annotations, prompts, and new tools: `fastr_get`, `fastr_list`, `fastr_pin`, `fastr_forget`).
-- **PR #8**: Skills suite consolidation, plugin manifest, and CI validation runner.
-- **PR #9**: VS Code extension headless activation fallback and staging trap decorations.
-- **PR #10**: Isolated benchmark database harnesses and calibrated baselines.
-- **PR #11**: Planetary Dashboard v2 overhaul with shadcn/ui, Tailwind CSS v4, and live cross-process sync.
-
----
-
-### 🗺️ Open Contribution Roadmap
-
-| Domain / Focus Area | What Needs Building | Difficulty | Reference Location | Target PR Scope |
-| :--- | :--- | :--- | :--- | :--- |
-| **Agent Hook Installers** | Auto-wire hooks & skills for Windsurf, Roo Code, Continue, and Warp | `good first issue` | [src/installer/setup.ts](src/installer/setup.ts) | `feat(installer)` |
-| **Local Embedding Providers** | Optional on-device backends (Ollama, llama.cpp, WebGPU) with air-gapped fallback | Intermediate | [src/search/embeddings.ts](src/search/embeddings.ts) | `feat(embeddings)` |
-| **IDE Extensions** | JetBrains (IntelliJ / WebStorm) and Neovim Lua plugin with status bar pill & trap underlines | Advanced | [extensions/vscode/](extensions/vscode/) | `feat(ide)` |
-| **Benchmark Runners** | SWE-bench and additional public QA scenario runners; LongMemEval and LoCoMo retrieval harnesses already exist | `good first issue` | [src/bench/benchmark.ts](src/bench/benchmark.ts) | `feat(bench)` |
-| **UI Visualizations** | Custom Three.js shaders, Treemap color palettes, and SVG/PNG graph exports | Intermediate | [ui/src/components/](ui/src/components/) | `feat(ui)` |
-
----
-
-### 🚀 Pull Request Workflow
-
-1. **Fork & Clone Repository**:
-   ```bash
-   git clone https://github.com/<your-username>/fastrmemory.git
-   cd fastrmemory
-   ```
-
-2. **Install Dependencies & Verify Test Suite (282 Tests Passing)**:
-   ```bash
-   npm install
-   npm test
-   ```
-
-3. **Create a Feature Branch**:
-   ```bash
-   git checkout -b feat/add-windsurf-hooks
-   # or for bug fixes:
-   git checkout -b fix/sqlite-busy-retry
-   ```
-
-4. **Implement Changes & Verify All Packages Compile**:
-   ```bash
-   # Compiles backend, React UI, and VS Code extension
-   npm run build:all
-   npm test
-   ```
-
-5. **Commit with DCO Sign-off (`-s`) & Open Pull Request**:
-   ```bash
-   git commit -s -m "feat(installer): add windsurf auto-hook integration"
-   git push origin feat/add-windsurf-hooks
-   ```
-
----
-
-### 📋 Pull Request Quality Checklist
-
-Before submitting your PR, verify:
-- [ ] **Strict TypeScript**: `npm run build:all` passes without type errors.
-- [ ] **Zero External Daemons**: Engine runs in-process via Node.js WAL SQLite.
-- [ ] **100% Test Green**: `npm test` passes all 282 unit tests across 52 files.
-- [ ] **DCO Sign-off**: All commits signed off using `git commit -s` ([Developer Certificate of Origin](https://developercertificate.org/)).
-- [ ] **Pre-Merge Trap Guardian**: Run `fastrmemory guard --strict` to verify no active error traps are violated.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for full architectural guidelines, secret scrubbing rules, and local development environment setup.
-
----
-
 ## 📄 License
 
 Apache License 2.0. Built by **Fastrsoft**. Free for personal and commercial use.

package/dist/bin/fastr.js

@@ -10,6 +10,7 @@ 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, 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';
@@ -40,6 +41,9 @@ const BANNER = `
 \x1b[2m  ⚡ Sovereign Cognitive Agent Memory • Zero Daemon • Native Node 24 WAL\x1b[0m
 `;
 const program = new Command();
+// Let subcommands own options that also exist on their parent (for example `mcp --project`
+// and `mcp init --project`) without the parent consuming the subcommand's value.
+program.enablePositionalOptions();
 program
     .name('fastrmemory')
     .alias('fastr')
@@ -61,7 +65,7 @@ program
     runInteractiveSetup();
 });
 // 1. MCP stdio command (Primary integration for Claude Code, Cursor, Antigravity)
-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)')
@@ -75,6 +79,65 @@ program
         process.exit(1);
     }
 });
+mcpCmd
+    .command('init')
+    .description('Configure FastrMemory MCP in Claude Code, Cursor, VS Code, OpenCode, or another client')
+    .requiredOption('--client <clients>', 'Client id, comma-separated ids, or all')
+    .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('--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)
+    .addHelpText('after', `
+Examples:
+  $ fastrmemory mcp init --client claude
+  $ 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 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);
+        const clients = parseMcpClients(options.client, scope);
+        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,
+            projectRoot: options.project,
+            channel,
+            runner,
+            profile,
+            source,
+            dryRun: options.dryRun,
+        });
+        if (options.json) {
+            console.log(JSON.stringify({ scope, channel, runner, profile, source, results }, null, 2));
+            return;
+        }
+        for (const result of results) {
+            console.log(formatMcpInitResult(result));
+        }
+        if (results.some((result) => result.manual)) {
+            console.log('\nRestart the client after adding the snippet above.');
+        }
+        else if (!options.dryRun) {
+            console.log('\nRestart the client so it picks up the FastrMemory MCP server.');
+        }
+    }
+    catch (err) {
+        console.error(`FastrMemory MCP init error: ${err.message}`);
+        process.exitCode = 1;
+    }
+});
 // 2. Init command
 program
     .command('init')