@gmickel/gno 1.40.0 → 1.41.0

package/README.md

@@ -725,6 +725,7 @@ Open `http://localhost:3000` to:
 - **Create in place**: New notes in the current folder/collection with presets and command-palette flows
 - **Capture with provenance**: `gno capture` and Web UI Quick Capture write quick notes to an editable collection with structured `source:` metadata, typed preset scaffolds, and a receipt that separates write, sync, and embed state
 - **Same capture contract everywhere**: CLI, MCP `gno_capture`, REST `/api/capture`, SDK `client.capture()`, and Web UI Quick Capture return the same provenance receipt shape
+- **Agent memory**: `gno remember` / `gno recall` (also MCP, REST, SDK) store single facts with explicit scopes and supersession, and return budgeted, cited recall with a fencing receipt. See [Memory](docs/MEMORY.md).
 - **Browser clipper**: npm-distributed unpacked Chromium extension for explicit
   visible selection or Reader capture through a local preview/confirm flow.
   See [Browser Clipper](docs/integrations/browser-clipper.md).

package/assets/skill/SKILL.md

@@ -88,6 +88,7 @@ Recipe rules:
 | **Models**   | `models list/use/pull/clear/path`                                                                          | Manage local AI models                                                   |
 | **Serve**    | `serve`, `daemon`                                                                                          | One resident Web/headless gateway and watcher                            |
 | **Publish**  | `publish export`                                                                                           | Export gno.sh publish artifacts                                          |
+| **Memory**   | `remember`, `recall`                                                                                       | Fact-granular agent memory with explicit scopes and supersession         |
 | **MCP**      | `mcp`, `mcp install/uninstall/status`                                                                      | AI assistant integration                                                 |
 | **Skill**    | `skill install/uninstall/show/paths`                                                                       | Install skill for AI agents                                              |
 | **Admin**    | `peek`, `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`                                        | Snapshot, maintenance, and diagnostics                                   |
@@ -552,6 +553,22 @@ search must include the new note. Browser provenance fields are
 `extractionHash`, `finalBodyHash`, `clipIdentity`, and `previewDigest`—do not
 invent `sourceHash`.
 
+## Memory (remember/recall)
+
+Use `gno remember` / `gno recall` (MCP `gno_remember` / `gno_recall`) for one
+fact that may later change, not for documents (`gno capture`) or edits to
+existing notes. They work only on a collection with `memoryManaged: true`.
+
+- Explicit `--scope` is required on every call (repeatable, 1-8); there is no
+  implicit global scope.
+- `recall` returns current facts with `gno://` cites plus a content-free
+  receipt; pass it back as `remember --receipt` so recalled text is not
+  re-stored as a new fact.
+- `remember` without a decision returns candidates and writes nothing; decide
+  with `--add` or `--supersede <uri> --predecessor-hash <hash>` from recall.
+- Details, error codes, and the fence's paraphrase limit: `docs/MEMORY.md`,
+  [cli-reference.md](cli-reference.md), [mcp-reference.md](mcp-reference.md).
+
 ## Reference-Safe Rename and Move
 
 When MCP writes are enabled and the user asks to rename or move an editable

package/assets/skill/cli-reference.md

@@ -190,6 +190,54 @@ Important behavior:
 - Capture syncs the file into FTS but does not imply embedding unless
   `embed.status` is `completed`.
 
+## Memory
+
+Fact-granular agent memory in a collection configured with
+`memoryManaged: true`. Use `gno capture` for documents; use `remember` for one
+fact that may later be superseded. Full contract: `docs/MEMORY.md`.
+
+### gno remember
+
+Store one fact, or propose candidates without writing.
+
+```bash
+gno remember "Prod deploys from main only" --scope project:gno            # candidates only, no write
+gno remember "Prod deploys from main only" --scope project:gno --add      # write a new fact
+gno remember "Prod deploys from release/*" --scope project:gno \
+  --supersede gno://memory/facts/... --predecessor-hash <hash> --json     # replace a fact
+gno remember "..." --scope family --scope shared --collection memory --add --source "standup 2026-09-03"
+```
+
+- `--scope` is required and repeatable (1-8); there is no implicit global
+  scope. `--collection` may be omitted only when exactly one memory-managed
+  collection exists.
+- No decision flag returns `outcome: "candidates"` (likely matches in scope)
+  and writes nothing. Decide with `--add`, or `--supersede <uri>` plus
+  `--predecessor-hash <hash>` taken from `gno recall`.
+- An exact duplicate returns `existing`; a lost supersede race exits 4
+  (`MEMORY_SUPERSEDE_CONFLICT`): recall again and decide again.
+- `--receipt <recall.json>` fences replays of recalled spans;
+  `--derived-from gno://...` is rejected. `--source <text>` stores evidence.
+- `--caller` / `--session` default from `$GNO_MEMORY_CALLER` /
+  `$GNO_MEMORY_SESSION`, then `cli:<user>` / `ppid:<pid>`.
+
+### gno recall
+
+Budgeted, cited recall of current facts (superseded ones excluded).
+
+```bash
+gno recall "deploy branch" --scope project:gno
+gno recall "kindergarten" --scope family --max-facts 3 --max-tokens 256 --json > receipt.json
+```
+
+- Same `--scope` / `--collection` / identity rules as `remember`.
+- Each fact carries its `gno://` URI, `contentHash`, scopes, identity, and
+  egress lineage; the result includes a content-free `receipt` to hand back
+  to `remember --receipt`.
+- Retrieval is hybrid when the embedding model is already cached, else
+  lexical with the reason; recall never downloads a model.
+- Nothing in scope prints the self-teaching line naming `gno remember`.
+
 ## Search Commands
 
 ### gno search

package/assets/skill/mcp-reference.md

@@ -161,6 +161,30 @@ non-overwrite captures fail instead of replacing a late-arriving file. MCP
 capture syncs the file for FTS but does not auto-embed; run `gno_embed` or
 `gno_index` afterward when vector search should include it.
 
+## Memory
+
+`gno_recall` (read set) and `gno_remember` (write set, needs `--enable-write`)
+are the fact-granular memory contract over a collection configured with
+`memoryManaged: true`. Both require `collection` and explicit `scopes`
+(1-8, any-intersection visibility, no implicit global scope). Identity
+(`caller` / `session`) is mapped server-side from the MCP client name and
+transport session, never from tool arguments.
+
+- `gno_recall` with `query`, `collection`, `scopes`, optional `maxFacts` /
+  `maxTokens` returns current facts (superseded ones excluded), each with a
+  `gno://` cite, `contentHash`, and egress lineage, plus a content-free
+  `receipt`. Empty scope returns a `hint` naming `gno remember`.
+- `gno_remember` with `text`, `collection`, `scopes` and no `decision` returns
+  `outcome: "candidates"` and writes nothing. Pass `decision: "add"` for a
+  new fact or `decision: "supersede"` with `predecessorUri` +
+  `predecessorHash` from a recall. An exact duplicate returns `existing`; a
+  lost supersede race returns `MEMORY_SUPERSEDE_CONFLICT` (recall, decide
+  again).
+- Pass the recall `receipt` back on `gno_remember` so a recalled span cannot
+  be re-stored (`MEMORY_FENCED_REPLAY`); a `gno://` entry in `derivedFrom` is
+  rejected (`MEMORY_FENCED_DERIVED`). Optional `source` stores evidence.
+- Writes sync for FTS before returning and do not auto-embed.
+
 ## Uninstall
 
 ```bash

package/browser-extension/artifacts/gno-browser-clipper-v1.41.0.zip.sha256

@@ -0,0 +1 @@
+f4a45361cbd92fe4639a8ee69d3cc965290d120e6aae0fbc57752ae9aeb31f94  gno-browser-clipper-v1.41.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.40.0"
+  "version": "1.41.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -9,13 +9,13 @@ This document specifies the command-line interface for GNO, a local knowledge in
 
 ### Exit Codes
 
-| Code | Name        | Description                                                   |
-| ---- | ----------- | ------------------------------------------------------------- |
-| 0    | SUCCESS     | Command completed successfully                                |
-| 1    | VALIDATION  | Validation or usage error (bad args, missing required params) |
-| 2    | RUNTIME     | Runtime failure (IO, DB, conversion, model, network)          |
-| 3    | NOT_RUNNING | `--status`/`--stop` found no live matching process            |
-| 4    | BUSY        | Write-lease contention on `index` / `update` / `embed`        |
+| Code | Name        | Description                                                                                |
+| ---- | ----------- | ------------------------------------------------------------------------------------------ |
+| 0    | SUCCESS     | Command completed successfully                                                             |
+| 1    | VALIDATION  | Validation or usage error (bad args, missing required params)                              |
+| 2    | RUNTIME     | Runtime failure (IO, DB, conversion, model, network)                                       |
+| 3    | NOT_RUNNING | `--status`/`--stop` found no live matching process                                         |
+| 4    | BUSY        | Write-lease contention on `index` / `update` / `embed`; a lost `remember --supersede` race |
 
 ### Global Flags
 
@@ -84,6 +84,8 @@ equivalent files fail closed as ambiguous.
 | bench              | yes    | no      | no    | no   | no    | terminal |
 | ask                | yes    | no      | no    | yes  | no    | terminal |
 | capture            | yes    | no      | no    | no   | no    | terminal |
+| remember           | yes    | no      | no    | no   | no    | terminal |
+| recall             | yes    | no      | no    | no   | no    | terminal |
 | get                | yes    | no      | no    | yes  | no    | terminal |
 | multi-get          | yes    | yes     | no    | yes  | no    | terminal |
 | ls                 | yes    | yes     | no    | yes  | no    | terminal |
@@ -1613,6 +1615,141 @@ gno capture "meeting note" --quiet
 
 ---
 
+### gno remember
+
+Store one fact in a memory-managed collection. Thin adapter over the core
+memory service (`src/core/memory.ts`): the CLI never touches the store or the
+write lease directly.
+
+**Synopsis:**
+
+```bash
+gno remember <text> --scope <scope> [--scope <scope>...] [--collection <name>] [--decision add|supersede | --add | --supersede <uri>] [--predecessor <uri>] [--predecessor-hash <hash>] [--receipt <path>] [--derived-from <uri>...] [--source <text>] [--caller <id>] [--session <id>] [--json]
+```
+
+**Scope and collection (fail-closed):**
+
+- `--scope` is required and repeatable (1..8 scopes, normalized: trim,
+  lowercase, NFC, dedupe). A missing scope exits `VALIDATION` with a message
+  naming `--scope`. There is no implicit global scope.
+- `--collection` names a collection with `memoryManaged: true`. It may be
+  omitted only when exactly one memory-managed collection is configured. A
+  collection without the flag exits `VALIDATION` (`MEMORY_COLLECTION_UNMANAGED`).
+
+**Identity:**
+
+- `--caller` defaults to `$GNO_MEMORY_CALLER`, then `cli:<os user>`.
+- `--session` defaults to `$GNO_MEMORY_SESSION`, then `ppid:<parent pid>`.
+- Both are recorded in the fact frontmatter and bound into recall receipts.
+
+**Decision:**
+
+- No decision flag: candidate proposal only. Same-scope current facts are
+  matched (BM25 pool of 16; cosine >= 0.83 when an embedding model is cached,
+  else token Jaccard >= 0.5); nothing is written, `outcome: "candidates"`.
+- `--decision add` / `--add`: write a new fact file. An exact duplicate
+  (same content hash) returns the existing record idempotently
+  (`outcome: "existing"`).
+- `--decision supersede --predecessor <uri>` / `--supersede <uri>`: requires
+  `--predecessor-hash <hash>` (the predecessor's `contentHash` from recall).
+  Under the shared write lease the service verifies the predecessor exists,
+  is current, matches the hash, and has no successor; the successor carries
+  `supersedes: [<uri>]`. `--add` and `--supersede` are mutually exclusive.
+- A write returns success only after the file exists and lexical sync
+  completed; the fact is retrievable before the command exits.
+
+**Context fencing:**
+
+- `--receipt <path>` presents a recall receipt (the `recall --json` output or
+  its `receipt` object). Text whose normalized hash matches a receipted span
+  is rejected (`MEMORY_FENCED_REPLAY`).
+- `--derived-from <uri>` declares origins; any `gno://` origin is rejected
+  (`MEMORY_FENCED_DERIVED`).
+- Paraphrases that carry neither a receipt nor a lineage declaration cannot
+  be fenced.
+
+**Evidence:**
+
+- `--source <text>` records free-text evidence for the fact. It is written to
+  the fact frontmatter (`memory.source`) and echoed as `record.source` /
+  `source` on every fact in remember and recall results.
+
+**Output:**
+
+- `--json` prints the shared `RememberResult` (`outcome` of `existing` |
+  `candidates` | `added` | `superseded`, with `record` / `candidates`,
+  `absPath`, `sync`, and `matching`). `--json` wins over global `--quiet`;
+  quiet prints the record URI (or one candidate URI per line).
+- Terminal output states the outcome, URI, record id, content hash, scopes,
+  `Supersedes:` when present, sync state, and the matching mode.
+
+**Exit codes:** `VALIDATION` (1) for flag, scope, collection, identity,
+predecessor, and fence errors; `BUSY` (4) when another writer holds the lease
+(`MEMORY_WRITE_LEASE_BUSY`) or already superseded the predecessor
+(`MEMORY_SUPERSEDE_CONFLICT`); `RUNTIME` (2) when the file was written but
+lexical sync failed (`MEMORY_SYNC_FAILED`) or the successor's `supersedes`
+edge did not project (`MEMORY_SUPERSEDE_PROJECTION_FAILED`). The JSON envelope carries the core code in
+`details.memoryCode`.
+
+**Examples:**
+
+```bash
+gno remember "Finn's kindergarten starts at 08:30" --scope family --add
+gno remember "Prod deploys from main only" --scope project:gno --scope ops
+gno remember "Prod deploys from release/*" --scope project:gno --supersede gno://memory/facts/2026/... --predecessor-hash <hash> --json
+```
+
+---
+
+### gno recall
+
+Recall current facts from a memory-managed collection under a budget.
+
+**Synopsis:**
+
+```bash
+gno recall <query> --scope <scope> [--scope <scope>...] [--collection <name>] [--max-facts <n>] [--max-tokens <n>] [--caller <id>] [--session <id>] [--json]
+```
+
+**Behavior:**
+
+- `--scope`, `--collection`, `--caller`, and `--session` follow the
+  `gno remember` rules (fail-closed scope, memory-managed collection only).
+- Retrieval is BM25 plus a vector leg when the configured embedding model is
+  cached and vectors exist (`retrieval.mode` = `hybrid`, else `lexical` with
+  `retrieval.semanticUnavailable` explaining why). Query expansion, graph
+  expansion, and reranking are disabled. Scope and supersession filtering run
+  inside the retrieval query; superseded facts are never returned.
+- Budget: at most `--max-facts` facts (default 8) under `--max-tokens`
+  (default 512). Both must be positive integers. Recall never downloads a
+  model.
+- Every fact carries `uri` (`gno://`), `text`, `scopes`, `caller`,
+  `session`, `createdAt`, `contentHash`, `spanHash`, `supersedes`, `score`,
+  and `egressLineage`; the response carries a content-free `receipt`
+  (`caller`, `session`, `issuedAt`, `memoryIds`, `spanHashes`, `digest`) plus
+  `budget` and `retrieval`. Derived output inherits the strictest source
+  egress policy (`egressLineage`).
+- Empty recall prints the self-teaching line naming `gno remember`
+  (`hint` in JSON) and exits 0.
+
+**Output:** `--json` prints the shared `RecallResult`. Terminal output lists
+numbered facts with URI, text, scopes, hash, and identity, then `Budget:`,
+`Retrieval:`, and `Receipt:` lines. Quiet prints one URI per line.
+
+**Exit codes:** `VALIDATION` (1) for scope, collection, identity, and budget
+errors (a bad `--max-facts` / `--max-tokens` carries
+`details.memoryCode: MEMORY_BUDGET_INVALID` in the JSON envelope);
+`RUNTIME` (2) on retrieval failure.
+
+**Examples:**
+
+```bash
+gno recall "deploy branch" --scope project:gno
+gno recall "kindergarten" --scope family --max-facts 3 --json > receipt.json
+```
+
+---
+
 ### gno get
 
 Retrieve a single document by reference.
@@ -3851,6 +3988,8 @@ Write-lease contention on `index` / `update` / `embed` does not use the generic
 | `NO_COLOR`                 | Disable colored output (standard)                                                                                          |
 | `PAGER`                    | Pager for long output (default: less -R on Unix, built-in on Windows)                                                      |
 | `GNO_SKILLS_HOME_OVERRIDE` | Override home dir for skill user scope (testing)                                                                           |
+| `GNO_MEMORY_CALLER`        | Default `--caller` identity for `gno remember` / `gno recall`                                                              |
+| `GNO_MEMORY_SESSION`       | Default `--session` identity for `gno remember` / `gno recall`                                                             |
 | `CLAUDE_SKILLS_DIR`        | Override Claude skills directory                                                                                           |
 | `CODEX_SKILLS_DIR`         | Override Codex skills directory                                                                                            |
 | `CLAUDE_CONFIG_DIR`        | Claude Code config dir; `gno agents` resolves Claude's instruction file under it (suppressed by an explicit home override) |

package/spec/db/schema.sql

@@ -15,6 +15,7 @@
 --   doc_tags          - Document tags (frontmatter and user-added)
 --   doc_links         - Wiki and markdown links between documents
 --   doc_edges         - Derived semantic document relationships
+--   doc_memory_scopes - Indexed scopes for managed memory records
 --   activation_receipts - Bounded per-collection retrieval proof receipts
 --   retrieval_traces - Opt-in private retrieval trace headers
 --   retrieval_trace_runs/events/judgments - Bounded trace outcome records
@@ -533,6 +534,22 @@ CREATE TABLE IF NOT EXISTS doc_edges (
 CREATE INDEX IF NOT EXISTS idx_doc_edges_src_type ON doc_edges(src_doc_id, edge_type);
 CREATE INDEX IF NOT EXISTS idx_doc_edges_dst_type ON doc_edges(dst_doc_id, edge_type);
 
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Memory Scopes (indexed, filtered inside retrieval queries)
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- One row per (managed memory record, normalized scope). Rows exist only for
+-- records that pass the memory-record validator; malformed files carry no
+-- scopes and therefore never enter managed recall.
+CREATE TABLE IF NOT EXISTS doc_memory_scopes (
+  document_id INTEGER NOT NULL,
+  scope TEXT NOT NULL,
+  PRIMARY KEY (document_id, scope),
+  FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_doc_memory_scopes_scope ON doc_memory_scopes(scope, document_id);
+
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Saved Context Capsules (metadata only)
 -- ─────────────────────────────────────────────────────────────────────────────

package/spec/mcp.md

@@ -63,6 +63,11 @@ All write tools acquire an OS-backed advisory lock at `.mcp-write.lock` under th
 If another process holds the lock, tools return `LOCKED`.
 For async jobs, the lock is held for the full job duration.
 
+`gno_remember` is the one write tool whose adapter takes no lock of its own:
+the core memory service acquires the same `.mcp-write.lock` lease for every
+memory write, so an MCP remember and a CLI writer serialise on one lease. A
+lease that stays busy past the wait window returns `MEMORY_WRITE_LEASE_BUSY`.
+
 ### Resident Streamable HTTP boundary
 
 `gno serve` and `gno daemon` mount the same stateful MCP surface at `/mcp`.
@@ -1173,6 +1178,85 @@ returned.
 
 ---
 
+### gno_recall
+
+Budgeted, cited, current-state recall from a memory-managed collection
+(read set; registered without `--enable-write`).
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "What you need to know, phrased as the fact would be stated"
+    },
+    "collection": {
+      "type": "string",
+      "description": "Memory-managed collection to recall from"
+    },
+    "scopes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "maxItems": 8,
+      "description": "Explicit scopes; visibility is any-intersection, no implicit global scope"
+    },
+    "maxFacts": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 64,
+      "description": "Fact budget (default 8)"
+    },
+    "maxTokens": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 8192,
+      "description": "Payload token budget (default 512)"
+    }
+  },
+  "required": ["query", "collection", "scopes"]
+}
+```
+
+**Response (`structuredContent`):** the shared `RecallResult` contract from
+`src/core/memory.ts` (one schema across CLI, MCP, REST, SDK):
+
+- `facts[]` — current facts only (superseded records excluded), each with
+  `uri` (`gno://` cite), `docid`, `recordId`, `text`, `scopes`, `caller`,
+  `session`, `createdAt`, `contentHash`, `supersedes`, `score`, `spanHash`,
+  `egressLineage`
+- `receipt` — content-free fencing receipt: `caller`, `session`, `issuedAt`,
+  `memoryIds`, `spanHashes`, `digest`
+- `budget` — `maxFacts`, `maxTokens`, `usedTokens`, `omitted`
+- `retrieval` — `mode` (`lexical` | `hybrid`) and `semanticUnavailable` when
+  the vector leg did not run
+- `egressLineage` — strictest source policy across returned facts (absent when
+  empty)
+- `hint` — self-teaching line naming `gno remember`, present only when no fact
+  was returned
+
+**Identity:** `caller` is the MCP client implementation name from the
+`initialize` handshake (`mcp` when absent); `session` is the Streamable HTTP
+session id, or the per-process server instance id on stdio. Tool arguments
+never carry identity.
+
+**Notes:**
+
+- Scope filtering executes inside the retrieval query, before any limit
+- The MCP adapter runs the lexical leg; `retrieval.mode` reports `lexical`
+  and `retrieval.semanticUnavailable` states why
+- Annotations: `readOnlyHint: true`, `idempotentHint: true`
+
+**Errors:** `MEMORY_QUERY_REQUIRED`, `MEMORY_BUDGET_INVALID`,
+`MEMORY_COLLECTION_REQUIRED`, `MEMORY_COLLECTION_NOT_FOUND`,
+`MEMORY_COLLECTION_UNMANAGED`, `MEMORY_SCOPES_REQUIRED`,
+`MEMORY_SCOPES_INVALID`, `MEMORY_QUERY_FAILED`.
+
+---
+
 ### gno_capture
 
 Create a new document in a collection (write-enabled).
@@ -1311,6 +1395,112 @@ shared `gno://schemas/capture-receipt@1.0` contract.
 
 ---
 
+### gno_remember
+
+Store one fact with supersession semantics in a memory-managed collection
+(write-enabled). Remember is fact-granular: `gno_capture` creates documents,
+file edits update existing notes, `gno_remember` upserts a fact.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "text": {
+      "type": "string",
+      "description": "One fact, stated in full (single statement, not a document)"
+    },
+    "collection": {
+      "type": "string",
+      "description": "Memory-managed collection to write into"
+    },
+    "scopes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "maxItems": 8,
+      "description": "Explicit scopes; no implicit global scope"
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["add", "supersede"],
+      "description": "Omit to receive candidates without writing"
+    },
+    "predecessorUri": {
+      "type": "string",
+      "description": "gno:// URI of the fact being superseded (supersede only)"
+    },
+    "predecessorHash": {
+      "type": "string",
+      "description": "contentHash of the predecessor as returned by gno_recall (supersede only)"
+    },
+    "receipt": {
+      "type": "object",
+      "description": "Receipt from the gno_recall response the fact derives from",
+      "properties": {
+        "caller": { "type": "string" },
+        "session": { "type": "string" },
+        "issuedAt": { "type": "string" },
+        "memoryIds": { "type": "array", "items": { "type": "string" } },
+        "spanHashes": { "type": "array", "items": { "type": "string" } },
+        "digest": { "type": "string" }
+      }
+    },
+    "derivedFrom": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Declared origins; any gno:// origin is rejected"
+    },
+    "source": {
+      "type": "string",
+      "description": "Free-text evidence for the fact"
+    }
+  },
+  "required": ["text", "collection", "scopes"]
+}
+```
+
+**Response (`structuredContent`):** the shared `RememberResult` contract:
+
+- `outcome: "existing"` — exact duplicate in scope; `record` is the stored
+  fact, nothing written
+- `outcome: "candidates"` — likely matches and no `decision`; `candidates[]`
+  carry `similarity` and `match` (`exact` | `likely` | `weak`), nothing written
+- `outcome: "added" | "superseded"` — `record`, `absPath`, and
+  `sync.status` (`completed` before the call returns; the fact is lexically
+  searchable)
+- `matching` — `mode` (`semantic` | `lexical`), `threshold`, and
+  `semanticUnavailable` when lexical matching was used
+
+**Notes:**
+
+- `supersede` requires `predecessorUri` + `predecessorHash`; the predecessor
+  must be current in the same collection with a matching hash and no existing
+  successor, otherwise `MEMORY_PREDECESSOR_*` or `MEMORY_SUPERSEDE_CONFLICT`
+- Context fencing: text whose normalized hash matches a `spanHashes` entry on
+  the presented `receipt` returns `MEMORY_FENCED_REPLAY`; a `derivedFrom`
+  entry starting with `gno://` returns `MEMORY_FENCED_DERIVED`. A paraphrase
+  that carries neither is indistinguishable from an original fact and is not
+  fenced
+- The core service holds the shared write lease for the write and lexical
+  sync; the MCP adapter takes no lock of its own
+- Identity mapping is the same as `gno_recall`
+- Annotations: `readOnlyHint: false`, `destructiveHint: false`,
+  `idempotentHint: false`
+
+**Errors:** `WRITE_DISABLED`, `MEMORY_TEXT_REQUIRED`,
+`MEMORY_TEXT_TOO_LARGE`, `MEMORY_COLLECTION_REQUIRED`,
+`MEMORY_COLLECTION_NOT_FOUND`, `MEMORY_COLLECTION_UNMANAGED`,
+`MEMORY_SCOPES_REQUIRED`, `MEMORY_SCOPES_INVALID`,
+`MEMORY_DECISION_INVALID`, `MEMORY_PREDECESSOR_REQUIRED`,
+`MEMORY_PREDECESSOR_NOT_FOUND`, `MEMORY_PREDECESSOR_HASH_MISMATCH`,
+`MEMORY_SUPERSEDE_CONFLICT`, `MEMORY_FENCED_REPLAY`, `MEMORY_FENCED_DERIVED`,
+`MEMORY_WRITE_LEASE_BUSY`, `MEMORY_SYNC_FAILED`,
+`MEMORY_SUPERSEDE_PROJECTION_FAILED`, `MEMORY_QUERY_FAILED`.
+
+---
+
 ### gno_list_tags
 
 List all tags with document counts.
@@ -2402,6 +2592,10 @@ Resource errors use standard MCP error responses.
 - `PATH_NOT_FOUND` — Path does not exist
 - `JOB_CONFLICT` — Another job is already running
 - `LOCKED` — Another MCP process holds the write lock
+- `WRITE_DISABLED` — Write tool dispatched while writes are disabled
+- `MEMORY_*` — Memory contract errors from `gno_recall` / `gno_remember`;
+  the stable code set is `MemoryErrorCode` in `src/core/memory.ts` and each
+  tool section above lists the codes it returns
 
 ---