@pcircle/memesh 4.8.2 → 4.8.5

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "memesh",
       "source": "./",
       "description": "MeMesh \u2014 agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
-      "version": "4.8.2",
+      "version": "4.8.5",
       "author": {
         "name": "PCIRCLE AI"
       },

package/.claude-plugin/plugin.json

@@ -4,7 +4,8 @@
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "4.8.2",
+  "version": "4.8.5",
+  "mcpServers": "./.claude-plugin/mcp.json",
   "homepage": "https://github.com/PCIRCLE-AI/memesh",
   "repository": "https://github.com/PCIRCLE-AI/memesh",
   "license": "MIT",

package/.codex-plugin/mcp.json

@@ -0,0 +1,7 @@
+{
+  "memesh": {
+    "command": "node",
+    "args": ["./dist/mcp/server.js"],
+    "cwd": "."
+  }
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "memesh",
+  "description": "MeMesh — agentic memory for coding agents.",
+  "version": "4.8.5",
+  "mcpServers": "./.codex-plugin/mcp.json"
+}

package/AGENTS.md

@@ -24,11 +24,16 @@ host is recallable from all of them. Not installed yet? Follow
 3. **"What do you remember?"** — call `briefing` and relay its content. Do
    not answer from your own conversation context.
 4. **When you need another agent** — to hand off, to ask, to report back —
-   send a `message` before anything else. The host's own push tool (Claude
+   first use `message discover` with the exact project when you do not already
+   know the recipient. It lists only live registrations and their routing IDs,
+   host kind, declared model/current work, generation, and lease; missing
+   declarations remain unknown. Then send a `message`. The host's own push tool (Claude
    Code's `SendMessage`, a Codex queue) delivers a wakeup; it is not the
    record, and it cannot reach an agent on a different host or one that is
-   not running. `briefing` and SessionStart tell you when something is
-   waiting for you: `N messages waiting for "<project>" — fetch them`.
+   not running. Generic `briefing` and SessionStart context has no recipient
+   identity and stays quiet. Check an inbox with the exact `project` and
+   `recipient`; poll first, then fetch each returned `message_id`. Fetching
+   does not acknowledge.
 
 ## All 11 MCP tools
 
@@ -41,10 +46,10 @@ host is recallable from all of them. Not installed yet? Follow
 | `import` | Import a JSON export; `merge_strategy` (required): skip / append / overwrite |
 | `learn` | Record a structured lesson: error, root cause, fix, prevention |
 | `task_state` | Read or update where the work stands: goal / next / blocked / done |
-| `briefing` | The assembled work topology for a project — call once at session start |
+| `briefing` | The assembled work topology; exact `project` + `recipient` can surface only that recipient's unfetched deliveries |
 | `user_patterns` | Analyze work schedule, tool preferences, and focus areas from memory |
 | `improvement` | Propose an evidence-linked product improvement or read its status; only a human may accept/reject it |
-| `message` | **Contact another local agent** — hand off work, ask for a result, report a disposition. Send here first: the durable inbox is the record, host push is only delivery. Polling/fetching never implies acknowledgement |
+| `message` | Discover live agents, then exchange exact-recipient untrusted messages: durable JSON payload max 64 KiB; complete native envelope max 16 KiB with distinct `native_message_too_large` and `recipient_unavailable` errors; delivery reads/acceptance never imply ACK or disposition |
 
 ## Memory hygiene
 
@@ -86,6 +91,9 @@ Under Claude Code with the MeMesh plugin, hooks capture automatically:
 - **PreToolUse (Edit|Write)** surfaces memories related to the file being
   edited.
 - **PostToolUse (Bash)** records git commits with diff stats.
+- **PostToolUse (ExitPlanMode|AskUserQuestion)** reminds you to `remember` a
+  decision just made — once per tool per session. It only reminds; unlike
+  the hooks above, it writes nothing to the graph itself.
 - **Stop** captures session knowledge and turns failures into lessons.
 - **PreCompact** saves important knowledge before history is compressed.
 - **UserPromptSubmit** detects "remember this" intent in the prompt.
@@ -95,9 +103,11 @@ Under Claude Code with the MeMesh plugin, hooks capture automatically:
   you do.
 
 So under Claude Code: skip step 1 of the loop (the topology is already
-injected), and do not `remember` commits or session summaries by hand. Manual
-calls are for what hooks cannot see — decisions and their rationale, lessons
-worth keeping, and user-stated task state.
+injected), and do not `remember` commits or session summaries by hand. A
+decision made via `ExitPlanMode`/`AskUserQuestion` gets a reminder, not a
+write — act on it with a real `remember` call. Manual calls are still how
+decisions, their rationale, lessons worth keeping, and user-stated task state
+actually get stored.
 
 On a host with no hooks (Gemini CLI, Cursor, an MCP-only setup, …) the loop is
 fully manual, and it is worth running.

package/README.de.md

@@ -9,7 +9,7 @@
   <p align="center">
     <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
-    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-22c55e?style=flat-square" alt="Node" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.13.0-22c55e?style=flat-square" alt="Node" /></a>
     <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
   </p>
 </p>
@@ -21,6 +21,7 @@
 ### Neue Kollaborationsflächen
 
 - `message` gibt lokalen Agenten einen dauerhaften Exact-Recipient-Posteingang mit Cursor-Recovery und expliziten Receipts über MCP, HTTP und CLI.
+- `message discover` liefert ein begrenztes, projektbezogenes Verzeichnis aktiver Agenten mit Session, Principal, Host-Art, deklariertem Model/Work (oder ausdrücklich unbekannt) und aktiven Leases; es führt keine Nachrichten- oder Receipt-Aktion aus.
 - `improvement` verwandelt aktive Memories in evidenzverknüpfte Produktarbeits-Vorschläge; Agenten dürfen sie einreichen und ihren Status lesen, aber nur ein Mensch darf annehmen oder ablehnen.
 
 ## Installation
@@ -32,7 +33,7 @@
 /plugin install memesh@pcircle-memesh
 ```
 
-Claude Code neu starten. Eine `◉ MeMesh`-Statuszeile am Anfang der nächsten Session bedeutet: es zeichnet auf.
+Claude Code neu starten. Eine `◉ MeMesh`-Statuszeile am Anfang der nächsten Session bestätigt, dass der SessionStart-Hook seine Statusausgabe erzeugt hat.
 
 **Im Terminal** — die `memesh`-CLI, das Dashboard und der `memesh-mcp`-Server für Codex / Cursor und kompatible lokale MCP-Clients (braucht [Node 22.13+](https://nodejs.org)):
 
@@ -73,9 +74,9 @@ Alle Hosts, die mit derselben lokalen MeMesh-Instanz verbunden sind, teilen daue
 
 Die optionale sichere Host-Native-Wakeup-Laufzeit unterstützt derzeit macOS und Linux. MeMesh-Kernspeicher, dauerhafte Nachrichtenspeicherung und MCP-Tools bleiben unter Windows verfügbar; Host-Native-Wakeup unter Windows wird noch nicht unterstützt.
 
-- Heute verfügbar: Ein Sender kann eine Nachricht dauerhaft an genau einen lokalen Empfänger senden. Der Empfänger kann den Payload getrennt abrufen, nach einem Neustart mit einem opaken Cursor fortsetzen und Intake, Bestätigung, Workflow-Status und Host-Aktivierung getrennt protokollieren.
-- Mit aktiviertem MeMesh-Codex-Plugin und dem owner-private Opt-in `memesh agent setup codex-session` erhält eine aktive Codex-Session im exakt konfigurierten lokalen Workspace ohne Polling oder menschliche Erinnerung einen nativen `memesh_message_available`-Wakeup. Der Marker enthält nur Routing-Metadaten; Codex ruft danach den dauerhaften Payload mit dem passend eingegrenzten `message`-Tool ab.
-- Eine erfolgreiche Queue-Annahme (`host_accept`) bedeutet nur, dass die lokale Codex-Queue den Marker annahm. Sie beweist nicht, dass ein Agent den Payload gelesen, bestätigt oder die Arbeit akzeptiert hat.
+- Heute verfügbar: Ein Sender über MCP, HTTP oder CLI kann einen nicht vertrauenswürdigen, JSON-kodierten Payload von höchstens 65.536 UTF-8-Bytes (64 KiB) dauerhaft an genau einen lokalen Empfänger senden. Der Empfänger kann ihn getrennt abrufen, nach einem Neustart mit einem opaken Cursor fortsetzen und Intake, Bestätigung, Workflow-Status und Host-Aktivierung getrennt protokollieren.
+- Mit aktiviertem MeMesh-Codex-Plugin und dem owner-private Opt-in `memesh agent setup codex-session` erhält die exakt aktive Codex-Session eine vollständige Nachricht über ihre native Queue — ohne Polling oder menschliche Erinnerung und ohne zweiten Inbox-Abruf. Der vollständige native Envelope einschließlich Routing-Metadaten und Payload ist separat auf 16.384 Bytes (16 KiB) begrenzt. Ein Exact-Session-Send ist erst erfolgreich, wenn die native Queue ihn annimmt; ein zu großer Envelope meldet `native_message_too_large`, andere nicht verfügbare oder abgelehnte Sessions melden `recipient_unavailable`. Eingegrenzte Recovery-Daten bleiben erhalten, und Principal-Ziele behalten Durable Store-and-Forward bei.
+- Eine erfolgreiche Queue-Annahme (`host_accept`) bedeutet nur, dass die lokale Codex-Queue die größenbegrenzte Nachricht annahm. Sie beweist nicht, dass ein Agent sie gelesen, bestätigt oder die Arbeit akzeptiert hat. Codex übernimmt den Text über das Prozessargument `--message`; deshalb kann eine Prozessinspektion desselben Benutzers ihn während des kurzen Queue-Aufrufs sehen. Native Nachrichten dürfen keine Secrets enthalten.
 - Der dauerhafte Nachrichtenspeicher wird durch eine Owner-Richtlinie begrenzt, nicht still gelöscht: `memesh message storage report` zeigt logische Payload-Größe, geschützte Zeilen, wiederverwendbare SQLite-Seiten und WAL-Größe. Das begrenzte Pruning ist standardmäßig ein Dry Run und tombstoniert nur alte terminale Payloads. Ein optionales `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES` lehnt einen zu großen Send atomar ab. Siehe [begrenzte Speicherung und Audit-Aufbewahrung](docs/platforms/agent-messaging.md#bounded-storage-and-audit-retention).
 - Eine gestoppte, fehlende oder getrennte Codex-Session wird weder geweckt noch ersetzt. Ihr dauerhafter Posteingang bleibt für Audit und Wiederherstellung erhalten; `poll` und `memesh message watch` sind Kompatibilitäts- und Diagnosepfade. Native Zustellung setzt keine beendete Modell-Session fort, führt keinen Payload aus und gilt nicht als Bestätigung.
 - Kooperative Vertrauensgrenze: Der Empfängername ist eine logische Routing-ID, keine Anmeldung oder ACL pro Agent. Jeder Aufrufer mit Zugriff auf dieselbe lokale MeMesh-Instanz muss als vertrauenswürdiger Workspace-Teilnehmer gelten; Host-Adapter setzen weiterhin ihre eigenen Berechtigungen und menschlichen Freigaben durch.
@@ -163,7 +164,7 @@ Wenn Sie Claude Code nutzen, installieren Sie MeMesh als Plugin direkt in der CL
 
 Claude Code verdrahtet Hooks, Skills und den MCP-Server automatisch. Sie erhalten Auto-Capture in der Session, proaktives Recall, den `/memesh`-Skill in der Unterhaltung und `remember` / `recall` / `forget` / `learn` als MCP-Tools für den Agenten.
 
-**Prüfen:** Claude Code neu starten und eine beliebige Session beginnen. Eine Statuszeile wie `◉ MeMesh ready · no memories for "your-project" yet` erscheint oben — diese Zeile IST das funktionierende Plugin; kein separater Befehl nötig. (Mit vorhandenen Memories zeigt sie stattdessen Zähler.)
+**Prüfen:** Claude Code neu starten und eine beliebige Session beginnen. Eine Statuszeile wie `◉ MeMesh ready · no memories for "your-project" yet` erscheint oben — sie bestätigt direkt die Statusausgabe des SessionStart-Hooks. Sie allein beweist nicht, dass spätere Capture- oder Recall-Vorgänge funktionieren. (Mit vorhandenen Memories zeigt sie stattdessen Zähler.)
 
 ### Option B — npm global (optionale Optimierung)
 
@@ -293,7 +294,7 @@ Decisions and direction for "your-project":
 - [decision] Use FTS5 as the retrieval baseline
 ```
 
-Denselben Block erhält Claude Code automatisch beim Session-Start, und jeder andere MCP-Client über das `briefing`-Tool — der Agent startet orientiert, statt das Repository neu zu lesen, und Sie erklären letzte Woche nicht noch einmal. Das Dashboard (`memesh serve`) ist die vollständige visuelle Ansicht.
+Denselben Block erhält Claude Code automatisch beim Session-Start, und jeder andere MCP-Client über das `briefing`-Tool — der Agent startet orientiert, statt das Repository neu zu lesen, und Sie erklären letzte Woche nicht noch einmal. Das Dashboard (`memesh serve`) ist die vollständige visuelle Ansicht. Ein allgemeiner `briefing`-Aufruf oder SessionStart-Kontext hat keine Empfängeridentität und meldet daher keine ungelesenen Nachrichten. Zum Prüfen eines Postfachs geben Sie den exakten `project` und `recipient` an; MeMesh meldet nur dessen noch nicht abgerufene Zustellungen und verweist zuerst auf Polling, dann auf Fetch.
 
 ### Ihre Daten
 
@@ -388,7 +389,7 @@ Reproduktionsbefehle, Datensatz-SHA256, rohe Ergebnisse pro Frage und Analyse be
 
 ## Was läuft in Claude Code automatisch ab
 
-Sie müssen nicht manuell alles speichern. MeMesh verfügt über **8 Hooks**, die Wissen während der Arbeit erfassen und injizieren:
+Sie müssen nicht manuell alles speichern. MeMesh verfügt über **9 Hooks**, die Wissen während der Arbeit erfassen und injizieren:
 
 | Wenn | Was MeMesh tut |
 |------|------------------|
@@ -396,10 +397,11 @@ Sie müssen nicht manuell alles speichern. MeMesh verfügt über **8 Hooks**, di
 | **Vor Dateibearbeitungen** | Ruft Memories ab, die an die Datei oder das Projekt gebunden sind, bevor Claude Code schreibt |
 | **Wenn Sie etwas zu merken bitten** | Erkennt „remember this“-/„guardar en memesh“-/„sauvegarder dans memesh“-/„記下來“-Absicht und erinnert an MeMesh |
 | **Nach jedem `git commit`** | Erfasst Ihre Änderungen mit Diff-Statistiken |
+| **Nachdem ein Plan genehmigt oder eine Frage beantwortet wurde** | Erinnert Claude daran, die Entscheidung mit `remember` zu speichern, falls sie es wert ist — höchstens einmal pro Tool und Session |
 | **Wenn Claude stoppt** | Erfasst bearbeitete Dateien und behobene Fehler; generiert automatisch strukturierte Lektionen aus Fehlern |
 | **Vor Context-Verdichtung** | Speichert Wissen, bevor es durch Context-Limits verloren geht |
 | **Vor riskanten Befehlen und Edits** | Löst die von Ihnen akzeptierten Lektions-Guards aus — eine Warnung genau in dem Moment, in dem sich ein erfasster Fehler wiederholen würde |
-| **Wenn eine optierte Codex-Session startet oder fortgesetzt wird** | Registriert genau diesen aktiven Thread für metadata-only MeMesh-Wakeups; andere Workspaces und gestoppte Sessions werden nicht angehängt |
+| **Wenn eine optierte Codex-Session startet oder fortgesetzt wird** | Registriert genau diesen aktiven Thread für die native Zustellung größenbegrenzter vollständiger Nachrichten; andere Workspaces und gestoppte Sessions werden nicht angehängt |
 
 > **Jederzeit abschalten:** `export MEMESH_AUTO_CAPTURE=false`
 
@@ -562,10 +564,10 @@ Wechselst du zu einer anderen Dimension (z. B. 768 → 1536), wird **nichts gel
 | `import` | Memories mit Merge-Strategien importieren (Skip / Overwrite / Append) |
 | `learn` | Strukturierte Lektionen aus Fehlern erfassen (Fehler, Grundursache, Behebung, Prävention) |
 | `task_state` | Arbeitsstand lesen oder festhalten — Ziel, nächster Schritt, Blocker, gerade Erledigtes |
-| `briefing` | Die zusammengesetzte Arbeits-Topologie — derselbe Block, den Claude Code beim Session-Start erhält, für jeden MCP-Client |
+| `briefing` | Die Arbeitstopologie für jeden MCP-Client; allgemeiner Kontext bleibt still, während exakte Angaben für `project` + `recipient` nur dessen noch nicht abgerufene Zustellungen anzeigen |
 | `user_patterns` | Arbeitsmuster analysieren — Zeitplan, Tools, Stärken, Lernbereiche |
 | `improvement` | Evidenzverknüpfte Produktverbesserung zur menschlichen Prüfung vorschlagen oder ihren Status lesen; Agenten können sie nicht selbst annehmen oder ablehnen |
-| `message` | Einen anderen lokalen Agenten erreichen (Arbeit übergeben, Ergebnis anfragen, Rückmeldung geben) — zuerst hier senden; der dauerhafte Posteingang ist der Beleg, Host-Push nur die Zustellung. Pollen, Abrufen und Quittieren sind getrennte Fakten |
+| `message` | Aktive Agenten finden und nicht vertrauenswürdige Nachrichten mit exaktem Empfänger austauschen. Dauerhafter JSON-Payload: max. 64 KiB; vollständiger nativer Envelope: max. 16 KiB mit getrennten Fehlern `native_message_too_large` und `recipient_unavailable`. Native Annahme, Discovery, Poll und Fetch bedeuten weder Bestätigung noch Workflow-Status |
 
 ---
 

package/README.md

@@ -9,7 +9,7 @@
   <p align="center">
     <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
-    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-22c55e?style=flat-square" alt="Node" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.13.0-22c55e?style=flat-square" alt="Node" /></a>
     <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
   </p>
 </p>
@@ -21,6 +21,7 @@
 ### New collaboration surfaces
 
 - `message` gives local agents a durable exact-recipient inbox with cursor recovery and explicit receipts over MCP, HTTP, and CLI.
+- `message discover` gives agents a bounded, project-scoped live directory with session, principal, host kind, declared model/work (or explicit unknown), and active leases; it performs no message or receipt operation.
 - `improvement` turns active memories into evidence-linked product-work proposals that agents can stage, but only a human can accept or reject.
 
 ## Install
@@ -32,7 +33,7 @@
 /plugin install memesh@pcircle-memesh
 ```
 
-Restart Claude Code. A `◉ MeMesh` status line at the top of your next session means it is capturing.
+Restart Claude Code. A `◉ MeMesh` status line at the top of your next session confirms the SessionStart hook emitted its status output.
 
 **In a terminal** — the `memesh` CLI, the dashboard, and the `memesh-mcp` server for Codex / Cursor and compatible local MCP clients (needs [Node 22.13+](https://nodejs.org)):
 
@@ -64,9 +65,9 @@ MeMesh has a real cross-agent advantage: every host connected to the same local
 
 The optional secure host-native wakeup runtime currently supports macOS and Linux. Core MeMesh memory, durable message storage, and MCP tools remain available on Windows; Windows host-native wakeup is not yet supported.
 
-- Works today: an MCP, HTTP, or CLI sender can durably send to one named local recipient. A receiver can fetch the payload separately, resume from an opaque cursor after restart, and record intake, acknowledgement, workflow disposition, and host activation as separate facts.
-- With the MeMesh Codex plugin enabled and the owner-private `memesh agent setup codex-session` opt-in, an active Codex session in the exact configured local workspace receives a native `memesh_message_available` wakeup without polling or a human reminder. The marker contains routing metadata only; Codex then fetches the durable payload with the scoped `message` tool.
-- A successful queue admission (`host_accept`) means only that the local Codex queue accepted the marker. It does not mean an agent read the payload, acknowledged it, or accepted the work.
+- Works today: an MCP, HTTP, or CLI sender can durably send one untrusted JSON-encoded payload of at most 65,536 UTF-8 bytes (64 KiB) to one named local recipient. A receiver can fetch it separately, resume from an opaque cursor after restart, and record intake, acknowledgement, workflow disposition, and host activation as separate facts.
+- With the MeMesh Codex plugin enabled and the owner-private `memesh agent setup codex-session` opt-in, an exact active Codex session receives one bounded full message through its native queue without polling or a human reminder, and without a second inbox fetch. The complete native envelope, including routing metadata and payload, is capped separately at 16,384 bytes (16 KiB). An exact-session send returns success only after that native queue accepts it; an oversized full envelope reports `native_message_too_large`, while other unavailable or rejected sessions report `recipient_unavailable`. Scoped recovery data remains durable. Principal targets retain durable store-and-forward behavior.
+- A successful native admission (`host_accept`) means only that the local Codex queue accepted the bounded message. It does not mean an agent read it, acknowledged it, or accepted the work. Codex currently exposes message text only through its `--message` argument, so same-user process inspection may observe it while the queue command runs; keep native messages free of secrets.
 - Durable message storage is bounded by owner policy, not silent deletion: `memesh message storage report` exposes logical payload, protected rows, reusable SQLite pages, and WAL size; bounded prune is dry-run by default and only tombstones old terminal payloads. An optional `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES` rejects a send atomically. See [bounded storage and audit retention](docs/platforms/agent-messaging.md#bounded-storage-and-audit-retention).
 - A stopped, missing, or disconnected Codex session is not awakened or replaced. Its durable inbox remains available for audit and recovery; `poll` and `memesh message watch` are compatibility and diagnostic paths. Native delivery never resumes a stopped model session, executes a payload, or implies acknowledgement.
 - Cooperative trust boundary: the recipient name is a logical routing ID, not a per-agent login or ACL. Every caller with access to the same local MeMesh instance must be treated as a trusted workspace participant; host adapters still enforce their own permissions and human-approval rules.
@@ -152,7 +153,7 @@ If you use Claude Code, install MeMesh as a plugin from inside the CLI:
 
 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.
 
-**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.)
+**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 — this directly verifies SessionStart hook output. It does not by itself prove later capture or recall behavior. (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.
 
@@ -230,6 +231,8 @@ The integration maps Hermes's `prefetch()` and `sync_turn()` hooks directly onto
 
 **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)**
 
+Current status: the source plugin is present under `extensions/memory-memesh/`, but it is not published or verified against a live OpenClaw runtime.
+
 ### 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.
@@ -294,7 +297,7 @@ 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.
+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. Generic `briefing` and SessionStart context has no recipient identity, so it does not report unread messages. To check an inbox, supply the exact `project` and `recipient`; MeMesh reports only that recipient's unfetched deliveries and directs the caller to poll before fetching each message.
 
 ### Your data
 
@@ -389,7 +392,7 @@ Re-runnable in ~10 seconds. Full instructions, dataset SHA256, raw per-question
 
 ## What Happens Automatically In Claude Code
 
-You don't need to manually remember everything. MeMesh has **8 hooks** that capture and inject knowledge while you work:
+You don't need to manually remember everything. MeMesh has **9 hooks** that capture and inject knowledge while you work:
 
 | When | What MeMesh does |
 |------|------------------|
@@ -397,10 +400,11 @@ You don't need to manually remember everything. MeMesh has **8 hooks** that capt
 | **Before editing files** | Recalls memories tied to the file or project before Claude writes code |
 | **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 |
+| **After a plan is approved or you answer a question** | Reminds Claude to `remember` the decision if it's worth keeping (once per tool per session) |
 | **When Claude stops** | Captures files edited, errors fixed, and auto-generates structured lessons from failures |
 | **Before context compaction** | Saves knowledge before it's lost to context limits |
 | **Before risky commands and edits** | Fires the lesson-guards you accepted — a warning at the exact moment a recorded mistake is about to repeat |
-| **When an opted-in Codex session starts or resumes** | Registers that exact live thread for metadata-only MeMesh message wakeups; other workspaces and stopped sessions are not attached |
+| **When an opted-in Codex session starts or resumes** | Registers that exact live thread for bounded full-message native delivery; other workspaces and stopped sessions are not attached |
 
 > **Opt out anytime:** `export MEMESH_AUTO_CAPTURE=false`
 
@@ -578,10 +582,10 @@ If you switch to an embedder with a different dimension (e.g. 768 → 1536), **n
 | `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 |
+| `briefing` | The assembled work topology for any MCP client; generic context stays quiet, while exact `project` + `recipient` can surface only that recipient's unfetched deliveries |
 | `user_patterns` | Analyze your work patterns — schedule, tools, strengths, learning areas |
 | `improvement` | Stage an evidence-linked product improvement for human review, or read its status; agents cannot accept or reject it |
-| `message` | Contact another local agent — hand off work, ask for a result, report back — by sending here first; the durable inbox is the record, host push is only delivery. Poll, fetch, and receipt are separate facts |
+| `message` | Discover live agents, then exchange exact-recipient untrusted messages. Durable JSON payload max: 64 KiB; complete native envelope max: 16 KiB with distinct `native_message_too_large` and `recipient_unavailable` failures. Native acceptance, discovery, poll, and fetch never imply acknowledgement or disposition |
 
 ---
 
@@ -632,7 +636,16 @@ bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.s
 
 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.
 
-**npm-global installs** (`npm install -g @pcircle/memesh`) can self-update via `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+**npm-global installs** (`npm install -g @pcircle/memesh`) can self-update via `memesh update`. For a source checkout, with npm installed, run `git pull && npm install && npm run build`.
+
+**Codex plugin marketplace installs** (using the Codex CLI):
+
+```bash
+codex plugin marketplace add PCIRCLE-AI/memesh
+codex plugin add memesh@pcircle-memesh
+```
+
+For a stale marketplace snapshot, refresh it with `codex plugin marketplace upgrade pcircle-memesh`, then reinstall with `codex plugin remove memesh` followed by `codex plugin add memesh@pcircle-memesh`.
 
 Session start surfaces a one-line banner (throttled to once per 24h per version) when a newer release is available, and `memesh doctor` reports the upgrade target with the channel-specific command.
 

package/README.zh-TW.md

@@ -9,7 +9,7 @@
   <p align="center">
     <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
-    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-22c55e?style=flat-square" alt="Node" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.13.0-22c55e?style=flat-square" alt="Node" /></a>
     <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
   </p>
 </p>
@@ -21,6 +21,7 @@
 ### 新的協作入口
 
 - `message` 讓本機 agent 擁有可恢復 cursor、可明確記錄 receipt 的單一收件人耐久化 inbox，MCP、HTTP、CLI 三個 surface 都可用。
+- `message discover` 提供有界、限定 project 的活動 agent directory，回傳 session、principal、host kind、宣告的 model/work（或明確 unknown）與 active lease；不會進行訊息或 receipt 操作。
 - `improvement` 讓 active memories 直接進入有證據連結的產品工作提案；agent 能發起與查狀態，但只有人類能接受或拒絕。
 
 ## 安裝
@@ -32,7 +33,7 @@
 /plugin install memesh@pcircle-memesh
 ```
 
-重開 Claude Code。下一個 session 開頭出現 `◉ MeMesh` 狀態列，就代表它在記了。
+重開 Claude Code。下一個 session 開頭出現 `◉ MeMesh` 狀態列，代表 SessionStart hook 已輸出狀態列。
 
 **在終端機裡** — `memesh` CLI、儀表板，以及給 Codex / Cursor 與相容本機 MCP 用戶端用的 `memesh-mcp` server（需要 [Node 22.13+](https://nodejs.org)）：
 
@@ -73,9 +74,9 @@ MeMesh 有一個很強的跨代理優勢：凡是連到同一個本機 MeMesh in
 
 可選的安全 host-native 喚醒 runtime 目前支援 macOS 與 Linux。Windows 仍可使用 MeMesh 核心記憶、耐久化 message storage 與 MCP tools；Windows host-native 喚醒目前尚未支援。
 
-- 今天就能做的：MCP、HTTP 或 CLI sender 可把訊息耐久化送給一個指定的本機 recipient。接收端可另行擷取 payload、在重啟後用 opaque cursor 補收，並把 intake、acknowledgement、workflow disposition 與 host activation 分開記錄。
-- 啟用 MeMesh Codex plugin 並完成 owner-private 的 `memesh agent setup codex-session` opt-in 後，位於**確切設定本機 workspace** 的活動中 Codex session 可在沒有輪詢或人工提醒下收到原生 `memesh_message_available` 喚醒。marker 只含 routing metadata；Codex 接著以 scope 相符的 `message` tool 擷取耐久化 payload。
-- 成功的 queue admission（`host_accept`）只代表本機 Codex queue 接受了 marker；它不代表 agent 已讀 payload、已確認收到，或接受了工作。
+- 今天就能做的：MCP、HTTP 或 CLI sender 可把一份 JSON 編碼後不超過 65,536 UTF-8 bytes（64 KiB）的不受信任 payload 耐久化送給一個指定的本機 recipient。接收端可另行擷取、在重啟後用 opaque cursor 補收，並把 intake、acknowledgement、workflow disposition 與 host activation 分開記錄。
+- 啟用 MeMesh Codex plugin 並完成 owner-private 的 `memesh agent setup codex-session` opt-in 後，確切活動中的 Codex session 可在沒有輪詢或人工提醒下透過原生 queue 收到一則完整訊息，也不需要再次 fetch inbox。包含 routing metadata 與 payload 的完整 native envelope 另有 16,384 bytes（16 KiB）上限。exact-session send 只有在原生 queue 接受後才成功；完整 envelope 過大時回報 `native_message_too_large`，其他無法使用或拒絕的 session 則回報 `recipient_unavailable`。scope 相符的 recovery data 仍會保留，Principal target 在無法原生傳遞時仍保有 durable store-and-forward。
+- 成功的原生 admission（`host_accept`）只代表本機 Codex queue 接受了這則有界訊息；它不代表 agent 已讀、已確認收到，或接受了工作。Codex 目前只提供 `--message` 參數傳入文字，因此同一使用者的 process inspection 可能在 queue command 執行期間看到內容；原生訊息不要放 secrets。
 - Durable message storage 由 owner policy 控制，不會偷偷刪除未解決訊息：`memesh message storage report` 會顯示 logical payload、protected rows、可重用 SQLite pages 與 WAL 大小；bounded prune 預設只 dry-run，且只 tombstone 舊的 terminal payload。可選的 `MEMESH_AGENT_MESSAGE_STORAGE_QUOTA_BYTES` 會在交易內原子拒絕超額 send。詳見 [bounded storage and audit retention](docs/platforms/agent-messaging.md#bounded-storage-and-audit-retention)。
 - 已停止、缺失或斷線的 Codex session 不會被喚醒或取代。它的耐久化 inbox 仍可供稽核與復原；`poll` 與 `memesh message watch` 是相容與診斷路徑。原生傳遞不會自動恢復已停止的模型 session、不會執行 payload，也不代表已確認收到。
 - 協作式信任邊界：recipient 名稱只是邏輯 routing ID，不是每個 agent 各自登入的身分或 ACL。能存取同一本機 MeMesh instance 的 caller 都必須視為受信任的 workspace participant；host adapter 仍需自行落實權限與人工核准規則。
@@ -163,7 +164,7 @@ npm install -g @pcircle/memesh
 
 Claude Code 會自動接好 hooks、skills 和 MCP server。你會獲得對話內自動擷取、主動回憶、可在 Claude Code 對話中使用的 `/memesh` skill（remember / recall / learn / forget），以及代理可呼叫的 `remember` / `recall` / `forget` / `learn` MCP 工具。
 
-**驗證方式：**重開 Claude Code、開任何 session。開頭出現像 `◉ MeMesh ready · no memories for "your-project" yet` 的狀態列 — 那一行就是外掛在運作的證明，不需要另外跑指令。（有記憶之後會改顯示數量。）CLI 與本地儀表板無需任何額外的全域安裝就能完整使用 — `npx @pcircle/memesh <command>` 可執行所有 CLI 指令，`npx @pcircle/memesh` 可在 `localhost:3737` 啟動儀表板。MCP server 直接從外掛內建的編譯產物啟動 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地建置步驟。memesh 透過 Node 內建的 `node:sqlite`（22.13+）存放資料，所以升級 Node 不會留下一個為錯誤 runtime 編譯的二進位檔。
+**驗證方式：**重開 Claude Code、開任何 session。開頭出現像 `◉ MeMesh ready · no memories for "your-project" yet` 的狀態列 — 這直接驗證 SessionStart hook 有輸出；單憑這一行不能證明後續 capture 或 recall 已運作。（有記憶之後會改顯示數量。）CLI 與本地儀表板無需任何額外的全域安裝就能完整使用 — `npx @pcircle/memesh <command>` 可執行所有 CLI 指令，`npx @pcircle/memesh` 可在 `localhost:3737` 啟動儀表板。MCP server 直接從外掛內建的編譯產物啟動 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地建置步驟。memesh 透過 Node 內建的 `node:sqlite`（22.13+）存放資料，所以升級 Node 不會留下一個為錯誤 runtime 編譯的二進位檔。
 
 ### 選項 B — npm 全域安裝（可選最佳化）
 
@@ -236,6 +237,8 @@ codex mcp list       # memesh 應顯示為 enabled
 
 **與 Hermes 的關鍵差異**：OpenClaw 的自動擷取有門檻控制（觸發時每輪最多 3 筆記憶），而非每一輪都擷取。整合對應到 MeMesh 的 HTTP API（`/v1/recall`、`/v1/remember`、`/v1/forget`）。完整 TypeScript 外掛合約、設定形狀與陷阱：**[docs/platforms/openclaw.md](docs/platforms/openclaw.md)**
 
+目前狀態：source plugin 已存在於 `extensions/memory-memesh/`，但尚未發布，也尚未在真實 OpenClaw runtime 驗證。
+
 ### 第二步：保存一個決策
 
 > 下方的 bash 範例假設 `memesh` 已在 `PATH` 上（選項 B）。選項 A（純外掛）使用者有兩條等價路徑：在 Claude Code 對話中發問（`/memesh` skill 與 MCP 工具涵蓋同樣的流程），或將任何 shell 中的 `memesh` 替換為 `npx @pcircle/memesh` — 旗標相同，不需要全域安裝。
@@ -300,7 +303,7 @@ Decisions and direction for "your-project":
 - [decision] Use FTS5 as the retrieval baseline
 ```
 
-Claude Code 在 session 開始時自動收到的就是同一個區塊，其他 MCP 用戶端呼叫 `briefing` 工具也拿到同一份 — 代理一開場就有方向，不用重讀整個 repo，你也不用再重講上禮拜的事。儀表板（`memesh serve`）是完整的視覺化版本。
+Claude Code 在 session 開始時自動收到的就是同一個區塊，其他 MCP 用戶端呼叫 `briefing` 工具也拿到同一份 — 代理一開場就有方向，不用重讀整個 repo，你也不用再重講上禮拜的事。儀表板（`memesh serve`）是完整的視覺化版本。一般 `briefing` 與 SessionStart 情境不帶 recipient 身分，因此不會顯示未讀訊息。要檢查收件匣，請提供確切的 `project` 與 `recipient`；MeMesh 只回報該 recipient 尚未擷取的訊息，並要求先 poll，再逐筆 fetch。
 
 ### 你的資料
 
@@ -395,7 +398,7 @@ MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌
 
 ## Claude Code 自動進行的事情
 
-你不需要手動記住所有事情。MeMesh 有 **8 個 hooks**，會在你工作時自動擷取與注入知識：
+你不需要手動記住所有事情。MeMesh 有 **9 個 hooks**，會在你工作時自動擷取與注入知識：
 
 | 何時 | MeMesh 做什麼 |
 |------|------------------|
@@ -403,10 +406,11 @@ MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌
 | **編輯檔案前** | 回憶與檔案或專案相關的記憶，再讓 Claude 寫程式碼 |
 | **當你要求記住** | 偵測「remember this」／「guardar en memesh」／「sauvegarder dans memesh」／「記下來」意圖（5 種語言）並提醒 Claude 使用 memesh |
 | **每次 `git commit` 之後** | 記錄你的變更，包含 diff 統計 |
+| **計畫被核准或你回答問題後** | 提醒 Claude 用 `remember` 存下這個決策（如果值得留存）——每個 session 每種工具只提醒一次 |
 | **Claude 停止時** | 擷取已編輯的檔案、已修復的錯誤，並從失敗自動產生結構化教訓 |
 | **上下文壓縮前** | 在知識被上下文限制丟掉之前先保存 |
 | **危險指令與編輯前** | 觸發你接受過的教訓守衛——在記錄過的錯誤即將重演的那一刻發出警告 |
-| **已 opt-in 的 Codex session 啟動或恢復時** | 註冊該確切活動 thread 以接收 metadata-only MeMesh 訊息喚醒；其他 workspace 與已停止 session 不會被附掛 |
+| **已 opt-in 的 Codex session 啟動或恢復時** | 註冊該確切活動 thread 以接收有界完整訊息的原生傳遞；其他 workspace 與已停止 session 不會被附掛 |
 
 > **隨時退出：** `export MEMESH_AUTO_CAPTURE=false`
 
@@ -569,10 +573,10 @@ memesh config set embedder.provider openai          # or: ollama
 | `import` | 匯入記憶，包含合併策略（跳過 / 覆寫 / 追加） |
 | `learn` | 記錄來自錯誤的結構化教訓（錯誤、根本原因、修復、預防） |
 | `task_state` | 讀取或記下工作進度——目標、下一步、卡住的地方、剛完成的事 |
-| `briefing` | 組合好的工作拓撲——Claude Code 在 session 開始拿到的那個區塊，任何 MCP client 都拿得到 |
+| `briefing` | 提供給任何 MCP client 的工作拓撲；一般情境不顯示未讀訊息，確切的 `project` + `recipient` 才會顯示該收件者尚未擷取的訊息 |
 | `user_patterns` | 分析你的工作模式——時間表、工具、優勢、學習領域 |
 | `improvement` | 將有證據來源的產品改善送交人類審核，或讀取其狀態；agent 不能自行接受或拒絕 |
-| `message` | 要聯絡另一個本機 agent（交接工作、請求結果、回報處置）先送到這裡：耐久收件匣才是紀錄，host push 只是通知。輪詢、擷取、確認收到是分開記錄的事實 |
+| `message` | 先找出活動 agent，再交換確切收件者的不受信任訊息。Durable JSON payload 上限 64 KiB；完整 native envelope 上限 16 KiB，並區分 `native_message_too_large` 與 `recipient_unavailable`。原生接受、探索、輪詢與擷取都不代表 ACK 或 workflow disposition |
 
 ---
 
@@ -623,7 +627,16 @@ bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.s
 
 腳本會 fast-forward marketplace cache、把新版本放進 `~/.claude/plugins/cache/`、安裝 runtime deps，然後把 `installed_plugins.json` 重指向新版本。執行完請重啟 Claude Code 讓 MCP server 重連。
 
-**npm-global 安裝**（`npm install -g @pcircle/memesh`）可以直接 `memesh update` 自動更新。Source checkouts：`git pull && npm install && npm run build`。
+**npm-global 安裝**（`npm install -g @pcircle/memesh`）可以直接 `memesh update` 自動更新。Source checkout 請先安裝 npm，再執行 `git pull && npm install && npm run build`。
+
+**Codex plugin marketplace 安裝**（使用 Codex CLI）：
+
+```bash
+codex plugin marketplace add PCIRCLE-AI/memesh
+codex plugin add memesh@pcircle-memesh
+```
+
+若 marketplace snapshot 已過期，先執行 `codex plugin marketplace upgrade pcircle-memesh`，再用 `codex plugin remove memesh` 後重新執行 `codex plugin add memesh@pcircle-memesh`。
 
 Session 開始時，有新版本可下載時會跳一行 banner（每版本每 24 小時節流一次），`memesh doctor` 會回報升級目標版本與對應指令。