@pcircle/memesh 4.5.0 → 4.6.0

package/README.md

@@ -1,9 +1,9 @@
-🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
+🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [Deutsch](README.de.md)
 
 <p align="center">
-  <h1 align="center">MeMesh LLM Memory</h1>
+  <h1 align="center">MeMesh</h1>
   <p align="center">
-    <strong>Local memory for Claude Code and MCP coding agents.</strong><br />
+    <strong>Agentic memory for coding agents.</strong><br />
     One SQLite file. No Docker. No cloud required.
   </p>
   <p align="center">
@@ -16,32 +16,40 @@
 
 ---
 
-**MeMesh** — the open-source **memory layer** for Claude Code & MCP agents. One SQLite file. No cloud. Plugs into any LLM.
+**MeMesh** — open-source **agentic memory** for Claude Code & MCP coding agents: captured from the agent's real work, injected at the moment it acts, kept honest when it contradicts itself. One SQLite file. No cloud.
 
-## 95.60% R@5 on LongMemEval-S — beats Mem0 by 46 points
+## Install
 
-MeMesh's retrieval is **FTS5 alone** — no LLM, no embeddings on the hot path. Measured against the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark (500 questions, MIT-licensed):
+**In Claude Code** — type these in the chat (hooks, memory tools and the `/memesh` skill are wired automatically):
 
-| System | R@5 | Source |
-|---|---|---|
-| **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
-| MemPalace | 96.6% | Vendor self-report |
-| Supermemory | ~82% | Vendor estimate |
-| Zep | 63.8% | LongMemEval paper |
-| Mem0 | 49.0% | LongMemEval paper |
+```
+/plugin marketplace add PCIRCLE-AI/memesh
+/plugin install memesh@pcircle-memesh
+```
 
-Re-runnable in ~10 seconds. Full instructions, dataset SHA256, raw per-question results, and known-failure analysis: [`benchmarks/longmemeval/REPRODUCE.md`](benchmarks/longmemeval/REPRODUCE.md).
+Restart Claude Code. A `◉ MeMesh` status line at the top of your next session means it is capturing.
 
----
+**In a terminal** — the `memesh` CLI, the dashboard, and the `memesh-mcp` server for Codex / Gemini / Cursor (needs [Node 22.13+](https://nodejs.org)):
+
+```bash
+npm install -g @pcircle/memesh
+memesh doctor        # verifies this install end to end
+```
+
+Most Claude Code users eventually want **both** — they share one database and never conflict. Details, other agents, and upgrades: [Get Started](#get-started-in-60-seconds).
+
+> **Installing via an AI agent?** Point it at [llms-install.md](llms-install.md) — deterministic steps with per-step verification. Once installed, [AGENTS.md](AGENTS.md) tells it how to use memesh well.
 
 ## The Problem
 
-Your coding agent forgets between sessions. Every architecture decision, bug fix, failed test, and hard-won lesson has to be re-explained. Claude Code starts fresh, re-discovers old constraints, and burns context on things it should already know.
+Your coding agent doesn't just forget facts between sessions — it **repeats work**. It re-proposes the approach you rejected last month, trips over the same failing test, re-discovers the constraint that broke production in March, and asks you to re-explain the architecture it helped design.
+
+That's not a chat-history problem; it's an agent-memory problem. What needs to survive between sessions is the *work*: decisions with their reasons, failures with their fixes, and the links between them.
 
-**MeMesh gives coding agents persistent, searchable, evolving local memory.** Install with npm, memory lives in `~/.memesh/knowledge-graph.db`, plug into Claude Code or any MCP-compatible client.
+**MeMesh is that memory.** Hooks capture it from what the agent actually does (sessions, commits, failures — not manual notes), recall injects it at the moment the agent acts (session start, before file edits), and the knowledge-graph layer keeps it honest over time (supersession, LLM-judged conflict detection). Install with npm, memory lives in `~/.memesh/knowledge-graph.db`, plug into Claude Code or any MCP-compatible client.
 
 > [!IMPORTANT]
-> Actively developed — features may change between releases. [Open an issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues) for bugs or feature requests.
+> Actively developed — features may change between releases. [Open an issue](https://github.com/PCIRCLE-AI/memesh/issues) for bugs or feature requests.
 
 ---
 
@@ -65,7 +73,7 @@ flowchart TB
     subgraph paths["Two install paths"]
       direction LR
       A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
-      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
     end
 
     DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
@@ -84,7 +92,7 @@ flowchart TB
 | Get auto-capture (sessions → lessons → recall) in Claude Code | Path A (plugin) |
 | Run `memesh remember` / `memesh recall` / `memesh doctor` in any terminal | Path B (npm-global) |
 | Open the local dashboard via `memesh serve` (no `npx` lookup delay) | Path B (npm-global) |
-| Plug `memesh-mcp` into Cursor, Cline, or another MCP client | Path B (npm-global) |
+| Plug `memesh-mcp` into Codex CLI, Gemini CLI, Cursor, or another MCP client | Path B (npm-global) |
 | All of the above | **Install both** — they don't conflict |
 
 ### ⚠️ Installing the plugin does NOT install the CLI
@@ -111,41 +119,82 @@ If you only use memesh through Claude Code chat (never type `memesh` in a termin
 If you use Claude Code, install MeMesh as a plugin from inside the CLI:
 
 ```
-/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin marketplace add PCIRCLE-AI/memesh
 /plugin install memesh@pcircle-memesh
 ```
 
 Claude Code wires hooks, skills, and the MCP server automatically. You get in-session auto-capture, proactive recall, the `/memesh` skill (remember / recall / learn / forget) inside the Claude Code conversation, and `remember` / `recall` / `forget` / `learn` available as MCP tools to the agent.
 
-The MCP server runs directly from the plugin's bundled compiled output — no `npx` lookup, no build step needed. If the native `better-sqlite3` binding is missing on first start (e.g. after a Node major upgrade), the launcher self-heals by rebuilding it in-process.
+**Verify it:** restart Claude Code and start any session. A status line like `◉ MeMesh ready · no memories for "your-project" yet` appears at the top — that line IS the plugin working; no separate command needed. (Once you have memories, it shows counts instead.)
+
+The MCP server runs directly from the plugin's bundled compiled output — no `npx` lookup, no build step, and nothing to compile. memesh stores its data through `node:sqlite`, which is part of Node itself (22.13+), so a Node upgrade cannot leave it with a binary built for the wrong runtime.
 
 > **This installs the plugin only.** You can run CLI commands via `npx @pcircle/memesh <command>` if you absolutely don't want a global install, but typing plain `memesh` in a terminal will report `command not found`. To get a real shell `memesh` command, also run **Option B** below — both paths coexist and share the same memory database. The "Install paths at a glance" diagram above covers this.
 
 ### Option B — npm global (optional optimisation)
 
-If you want the binary directly on your shell `PATH` (so plain `memesh`, `memesh-mcp`, etc. work in any terminal without the per-call `npx` lookup), or you want to expose `memesh-mcp` as a fixed-path stdio command to **non-Claude-Code MCP clients** (Cursor, Cline, terminal-only flows):
+If you want the binary directly on your shell `PATH` (so plain `memesh`, `memesh-mcp`, etc. work in any terminal without the per-call `npx` lookup), or you want to expose `memesh-mcp` as a fixed-path stdio command to **non-Claude-Code MCP clients** (Codex CLI, Gemini CLI, Cursor, Cline, terminal-only flows):
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
 > **First-install notes (one-time):**
-> - **Native modules** — `better-sqlite3` and `sqlite-vec` install via prebuilt binaries on macOS (arm64/x64), Linux (x64/arm64), and Windows x64. On uncommon platforms or when prebuilds fail, you'll need a working C/C++ toolchain.
+> - **No compiler needed** — the database engine is Node's own `node:sqlite`. `sqlite-vec`, which adds meaning-based search, ships as a prebuilt file for macOS (arm64/x64), Linux (x64/arm64) and Windows x64; on any other platform it is simply absent and recall stays on keyword search. Nothing here runs an install script, so `npm install --ignore-scripts` installs a fully working memesh.
 > - **Semantic (meaning-based) search is optional** — the default recall path is FTS5 keyword search, which needs no model and no download. Meaning-based search needs an embedder: run [Ollama](https://ollama.com) locally, or configure a cloud embedder (see "Bring-your-own embeddings" below). Without one, memesh uses keyword search only.
 
 ### Step 1.5: Wire MeMesh into Claude Code (npm path only)
 
 If you installed via **Option A** (`/plugin install memesh@pcircle-memesh`), skip this step — Claude Code wires plugin hooks automatically.
 
-If you installed via **Option B** (`npm install -g`), the CLI is on your PATH and the MCP server is registered, but the Claude Code session hooks are not auto-wired. Without them you can still use `memesh remember` / `recall` manually, but the **auto-capture loop** (sessions → lessons → recall on next session) is silent.
+If you installed via **Option B** (`npm install -g`), the CLI is on your PATH — but nothing is wired into Claude Code yet: the npm package deliberately runs no install scripts, and the plugin (Option A) is what registers the MCP server and hooks inside Claude Code. What the npm path can wire by itself is the session hooks. Without them you can still use `memesh remember` / `recall` manually, but the **auto-capture loop** (sessions → lessons → recall on next session) is silent.
+
+```bash
+memesh setup                 # detects Claude Code / Codex / Gemini, offers to wire each, verifies
+```
+
+Or the individual steps by hand:
 
 ```bash
 memesh install-hooks         # adds memesh's hooks to ~/.claude/settings.json
-memesh doctor                # verifies "Hooks wired into Claude Code" passes
+memesh setup --check         # machine-level verification: reads the hosts' own config, changes nothing
 ```
 
 The hooks coexist with any custom hooks you already have under `~/.claude/hooks/` — `install-hooks` writes additive entries and never overwrites yours. To remove later: `memesh uninstall-hooks`.
 
+### Same memory from Codex CLI and Gemini CLI
+
+`memesh-mcp` is a plain stdio MCP server, so any MCP-capable host can talk to it — not just Claude Code. With Option B installed (`memesh-mcp` on your `PATH`), register it once per host:
+
+```bash
+# OpenAI Codex CLI — writes [mcp_servers.memesh] into ~/.codex/config.toml
+codex mcp add memesh -- memesh-mcp
+
+# Google Gemini CLI — user scope, so it works in every folder
+gemini mcp add -s user memesh memesh-mcp
+```
+
+Every host reads and writes the same `~/.memesh/knowledge-graph.db`, so a memory stored from a Claude Code session is recallable from Codex or Gemini, and the other way around. Verify from either host by asking it to call the `recall` tool, or from a terminal:
+
+```bash
+codex mcp list       # memesh should be listed as enabled
+gemini mcp list      # memesh should show "Connected"
+```
+
+> **Use `memesh-mcp`, not `npx -p @pcircle/memesh`, as the configured command.** `npx -p` resolves to the *local* package whenever the host's working directory is inside a checkout of this repository, silently running whatever state that working tree is in instead of the installed release.
+
+### Native integration: Hermes Agent
+
+**Hermes Agent** (NousResearch) has a first-party `MemoryProvider` plugin system — MeMesh integrates at the same tier as Hermes's own built-in memory backends (honcho, mem0, hindsight), not as an HTTP bridge. Unlike MCP mode where you manually call tools, Hermes's provider system runs `recall`/`remember` automatically on every turn.
+
+The integration maps Hermes's `prefetch()` and `sync_turn()` hooks directly onto MeMesh's HTTP API. Complete guide with provider code structure, config, and four real pitfalls from a live deployment: **[docs/platforms/hermes-agent.md](docs/platforms/hermes-agent.md)**
+
+### Native integration: OpenClaw
+
+**OpenClaw** has a first-party memory-capability plugin system — MeMesh integrates as a native memory provider at the same tier as OpenClaw's own built-in backends (LanceDB), not as an HTTP bridge. The plugin registers via `api.registerMemoryCapability()` and exposes `memory_recall`/`memory_store`/`memory_forget` tools plus automatic recall on the `before_prompt_build` hook.
+
+**Key difference from Hermes**: OpenClaw's auto-capture is threshold-gated (max 3 memories/turn when triggered), not every-turn. The integration maps onto MeMesh's HTTP API (`/v1/recall`, `/v1/remember`, `/v1/forget`). Full TypeScript plugin contract, config shape, and pitfalls: **[docs/platforms/openclaw.md](docs/platforms/openclaw.md)**
+
 ### Step 2: Store a decision
 
 > The bash examples below assume `memesh` is on your `PATH` (Option B). Option A (plugin-only) users have two equivalent paths: ask in the Claude Code conversation (the `/memesh` skill + MCP tools cover the same flows), or replace `memesh` with `npx @pcircle/memesh` in any shell — same flags, no global install needed.
@@ -193,6 +242,32 @@ memesh serve
   <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — interactive knowledge graph with type filters and ego mode" width="100%" />
 </p>
 
+### See what it remembered
+
+At any moment, one command prints what your agent knows about the current project — where work was left off, decisions, lessons, recent activity (wrapped as reference data):
+
+```bash
+memesh briefing
+```
+
+```text
+Where "your-project" was left off (today):
+- Goal: Ship the payment retry logic
+- Next: Open the PR once CI is green
+
+Decisions and direction for "your-project":
+- [decision] Use FTS5 as the retrieval baseline
+```
+
+This same block is what Claude Code receives automatically at session start, and what any other MCP client gets from the `briefing` tool — the agent starts oriented instead of re-reading the repository, and you stop re-explaining last week. The dashboard (`memesh serve`) is the full visual view.
+
+### Your data
+
+- **One local file.** Everything lives in `~/.memesh/knowledge-graph.db` — SQLite, on your disk. No cloud account; nothing leaves your machine unless you configure a cloud embedder or LLM yourself.
+- **Back up = copy that one file.** Restore = copy it back.
+- **Pause capture anytime**: `export MEMESH_AUTO_CAPTURE=false`.
+- **Delete everything**: remove `~/.memesh/`.
+
 ---
 
 ## Who Is This For?
@@ -261,15 +336,30 @@ Paste tools into any API call
 
 ---
 
+## Benchmarks — 95.60% R@5 on LongMemEval-S
+
+MeMesh's retrieval is **FTS5 alone** — no LLM, no embeddings on the hot path. Measured against the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark (500 questions, MIT-licensed):
+
+| System | R@5 | Source |
+|---|---|---|
+| **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | Vendor self-report |
+| Supermemory | ~82% | Vendor estimate |
+| Zep | 63.8% | LongMemEval paper |
+| Mem0 | 49.0% | LongMemEval paper |
+
+Re-runnable in ~10 seconds. Full instructions, dataset SHA256, raw per-question results, and known-failure analysis: [`benchmarks/longmemeval/REPRODUCE.md`](benchmarks/longmemeval/REPRODUCE.md).
+
+---
+
 ## What Happens Automatically In Claude Code
 
-You don't need to manually remember everything. MeMesh has **7 hooks** that capture and inject knowledge while you work:
+You don't need to manually remember everything. MeMesh has **6 hooks** that capture and inject knowledge while you work:
 
 | When | What MeMesh does |
 |------|------------------|
 | **Every session start** | Loads your most relevant memories + proactive warnings from past lessons |
 | **Before editing files** | Recalls memories tied to the file or project before Claude writes code |
-| **Before bash commands** | (Opt-in) Nudges Claude to dispatch high-verifiability commands (test, build, lint, migrate, deploy, benchmark) as background agents |
 | **When you ask to remember** | Detects "remember this" / "guardar en memesh" / "sauvegarder dans memesh" / "記下來" intent (5 languages) and reminds Claude to use memesh |
 | **After every `git commit`** | Records what you changed, with diff stats |
 | **When Claude stops** | Captures files edited, errors fixed, and auto-generates structured lessons from failures |
@@ -288,7 +378,6 @@ All configuration is via environment variables. Defaults are local-only and zero
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Override the SQLite database location. |
 | `MEMESH_AUTO_CAPTURE` | `true` | Disable the auto-capture hooks (`Stop`, `PreCompact`) entirely. |
 | `MEMESH_AUTO_DETECT_LLM` | unset (auto-detect **on**) | Set to `0` to stop memesh using an API key it finds in your shell env. By default, if `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` is set and you have not configured a provider in `~/.memesh/config.json`, memesh uses it for write-side LLM features (lesson extraction, auto-tagging, dream). Embeddings are unaffected — they stay keyword-only (FTS5) unless you explicitly set `embedder.provider` to `ollama` or `openai`. |
-| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | unset | Set to `1` to enable an experimental working-model protocol (CTO / Orchestrator / Agents framing). Adds a session-start banner, a Bash command nudge, and `verify_agent_work` telemetry. The protocol's effectiveness is being instrumented, not yet proven — opt in if you want to participate. **Default is OFF**: the core memory features work without this flag. |
 | `MEMESH_AUTO_UPDATE` | `off` | Auto-update policy. `off` (default) never auto-updates; `patch` allows `X.Y.Z → X.Y.Z+N`; `minor` adds `X.Y.Z → X.Y+1.0`; `major` allows any bump. When permitted, a detached `npm install -g` fires at session end (Stop hook) so it never blocks your work — outcomes land in `~/.memesh/auto-update.log`. Also settable as `autoUpdate` in `~/.memesh/config.json` (env wins). When the installed version is deprecated by maintainers (security advisory), `patch` is force-allowed even on `off` — minor / major bumps still stay manual to avoid silent behaviour drift. |
 | `OPENAI_API_KEY` | unset | Your OpenAI key. Used automatically for LLM features unless you set `MEMESH_AUTO_DETECT_LLM=0` or configure a provider explicitly. |
 | `OLLAMA_HOST` | `http://localhost:11434` | Override the Ollama endpoint when using a local Ollama provider. |
@@ -328,7 +417,7 @@ When npm flags an installed version as deprecated (typically a security advisory
 
 **🔄 Knowledge Evolution** — Decisions change. `forget` archives old memories (never deletes). `supersedes` relations link old → new. Your AI always sees the latest version.
 
-**⚠️ Conflict Detection** — If you have two memories that contradict each other, MeMesh warns you.
+**⚠️ Conflict Detection** — `memesh dream conflicts` has the LLM judge your semantically-closest memory pairs for contradiction, supersession or duplication, and stages what it finds as proposals. Nothing applies itself: you review with `dream list` / `dream show`, and only an accepted proposal creates the relation — after which every `recall` touching either memory carries the warning. Causality is never inferred from timestamps; verdicts come from what the memories actually say.
 
 **🕸️ Knowledge Graph Connectivity** — `memesh kg backfill-relations --all-rules` links orphan entities using tag co-occurrence, project clustering, session context, and name similarity — no LLM required.
 
@@ -350,6 +439,58 @@ Imported bundles stay searchable, but MeMesh does not auto-inject imported memor
 
 ---
 
+## Recipes
+
+### Catch a contradiction before it bites
+
+Two decisions, made weeks apart, that cannot both be true — the failure mode
+a memory layer exists to catch:
+
+```bash
+memesh remember --name retry-policy --type decision \
+  --obs "All HTTP clients retry failed requests up to 5 times with exponential backoff."
+# ...weeks later, someone decides the opposite...
+memesh remember --name retry-policy-v2 --type decision \
+  --obs "HTTP clients must never retry automatically — fail fast and surface the error."
+
+memesh dream conflicts        # the judge flags the pair, with its reasoning
+memesh dream show 1           # read the verdict, the excerpts, what accepting creates
+memesh dream accept 1         # YOU decide — nothing is ever linked automatically
+memesh recall "retry policy"  # → Warning: Conflicts detected
+```
+
+From then on, any assistant that recalls either decision is told they
+conflict — instead of confidently quoting whichever one it found first.
+
+### One memory, three assistants
+
+MeMesh is an MCP server, so the same SQLite file serves every MCP client on
+the machine. Register it once per tool (exact commands in
+[Get Started](#get-started-in-60-seconds)) and a decision recorded in Claude
+Code is recalled by Codex or Gemini CLI mid-session — no re-explaining, no
+copy-pasting context between vendors.
+
+### Record decisions so they stay findable
+
+Auto-capture keeps session history, but the memories that pay rent are the
+deliberate ones:
+
+```bash
+memesh remember --name auth-approach --type decision \
+  --obs "JWT with RS256; PKCE over implicit flow because the client is public." \
+  --tags "project:myapp" "topic:auth"
+```
+
+Then link consequences to their causes as they happen — from any MCP client,
+in plain words: *"remember this incident as a lesson, influenced by
+auth-approach"*. The `remember` tool takes free-form relations, and `caused` /
+`influenced` are the documented causal vocabulary (cause → effect, stated
+explicitly — MeMesh never infers causality from timestamps). Weeks later,
+`memesh recall "why did we pick PKCE"` returns the decision with its recorded
+consequences attached — reasoning you can follow, not just text that matched.
+
+---
+
 ## Unlock Smart Mode (Optional)
 
 MeMesh works offline by default — recall stays strictly LLM-free (95.60% R@5 on LongMemEval-S out of the box). Add an LLM API key only if you want LLM-augmented analysis flows on top: smarter session extraction, auto-tagging of new memories, lesson generation from failures, and `dream` compression:
@@ -392,7 +533,7 @@ The embedder is configured **independently of the chat LLM** — changing `llm.p
 
 ---
 
-## All 8 Memory Tools
+## All 9 Memory Tools
 
 | Tool | What it does |
 |------|-------------|
@@ -402,8 +543,9 @@ The embedder is configured **independently of the chat LLM** — changing `llm.p
 | `export` | Share memories as JSON between projects or team members |
 | `import` | Import memories with merge strategies (skip / overwrite / append) |
 | `learn` | Record structured lessons from mistakes (error, root cause, fix, prevention) |
+| `task_state` | Read or record where the work stands — goal, next step, blocker, what was just finished |
+| `briefing` | The assembled work topology — the same block Claude Code gets at session start, for any MCP client |
 | `user_patterns` | Analyze your work patterns — schedule, tools, strengths, learning areas |
-| `verify_agent_work` | Persist a verification report for background-agent work; reality-checks claimed file changes against `git diff` |
 
 ---
 
@@ -412,7 +554,7 @@ The embedder is configured **independently of the chat LLM** — changing `llm.p
 ```
                     ┌─────────────────┐
                     │   Core Engine   │
-                    │  (8 operations) │
+                    │  (7 operations) │
                     └────────┬────────┘
            ┌─────────────────┼─────────────────┐
            │                 │                 │
@@ -434,19 +576,22 @@ Claude Code's plugin marketplace pins versions at install time and does **not**
 
 **Option A — `/plugin` UI**: uninstall `memesh@pcircle-memesh`, then reinstall. Claude Code fetches the latest marketplace version.
 
-**Option B — one-line script** (no UI clicking, idempotent):
+**Option B — one command** (no UI clicking, idempotent; requires the npm CLI, `npm install -g @pcircle/memesh`):
+
+```bash
+memesh upgrade-plugin
+```
+
+It finds your installed plugin version, checks the prerequisites, and runs the bundled upgrade script for you. Prerequisites: `node`, `npm` and `rsync` on your PATH (macOS ships rsync; Debian/Ubuntu: `sudo apt install rsync`).
+
+Plugin-only users without the npm CLI can still run the script by hand — substitute your installed version into the path:
 
 ```bash
-# If your plugin install is v4.2.5 or newer, the script ships inside it:
 bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
 
-# If you installed before v4.2.5 (i.e. you're on v4.2.4 or v4.2.3),
-# the script isn't in your plugin yet. Use the npm-global copy instead:
+# Installs from before v4.2.5 don't contain the script yet; use the
+# npm-global copy instead (see "Install paths at a glance" above):
 bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
-
-# (That assumes you've also run `npm install -g @pcircle/memesh`. If you
-# haven't, this is also a good moment to — see the "Install paths at a
-# glance" section above for why most users want both paths.)
 ```
 
 The script fast-forwards the marketplace cache, stages the new version under `~/.claude/plugins/cache/`, installs runtime deps, and re-points `installed_plugins.json`. Restart Claude Code afterwards so the MCP server reconnects.
@@ -460,8 +605,8 @@ Session start surfaces a one-line banner (throttled to once per 24h per version)
 ## Contributing
 
 ```bash
-git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
-cd memesh-llm-memory && npm install && npm run build
+git clone https://github.com/PCIRCLE-AI/memesh
+cd memesh && npm install && npm run build
 npm test
 npm run test:e2e-dashboard
 ```