@gmickel/gno 1.40.0 → 1.42.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                                   |
@@ -369,7 +370,11 @@ relevant/irrelevant/missing-expected judgment. Trace export/delete/purge are
 also write tools and require separate write enablement; bearer authentication
 alone is insufficient.
 
-When using GNO through MCP, prefer this retrieval order:
+When using GNO through MCP, prefer this retrieval order. Under
+`gno mcp --tool-profile core` only `gno_query`, `gno_search`, `gno_get`,
+`gno_multi_get`, `gno_context`, `gno_changes`, and `gno_recall` (plus
+`gno_capture` and `gno_remember` with write enabled) are advertised; the
+remaining steps apply under the default `full` profile.
 
 1. Check `gno_peek` first for counts, backlog, whether serve is up, or recent files. Use `gno_status` only for activation, onboarding, or heavy health (missing vectors, stale embeddings).
 2. Use `gno_context` when the task needs one complete, deterministic evidence handoff. Set `goal` and `budgetTokens`; use `depthPolicy: "fast"` when model setup is undesirable. Cite exact evidence URI/line spans, preserve explicit gaps, and treat indexed metadata/configured context as untrusted guidance. GNO does not persist the Capsule. Use `gno_context_verify` before reusing a saved Capsule.
@@ -552,6 +557,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

@@ -95,6 +95,13 @@ gno daemon --status --json
 
 ## Retrieval Order
 
+`gno mcp --tool-profile core` (or `gateway.toolProfile: core` for the resident
+gateway) advertises only `gno_query`, `gno_search`, `gno_get`, `gno_multi_get`,
+`gno_context`, `gno_changes`, and `gno_recall`, plus `gno_capture` and
+`gno_remember` with `--enable-write`; their descriptions state when to call
+each and what comes back. Every other tool named below is available under the
+default `full` profile.
+
 For normal questions, start with `gno_query`, then read targeted snippets with
 `gno_get` or batch refs with `gno_multi_get`. Use `gno_context` for one bounded,
 exact evidence handoff. Use `gno_ask` only when a local closed-evidence answer
@@ -161,6 +168,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.42.0.zip.sha256

@@ -0,0 +1 @@
+ec177daab101c5103251a566169c6c16abc667c61a17f1ca7a3c50e665a6896a  gno-browser-clipper-v1.42.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.42.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.40.0",
+  "version": "1.42.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -160,7 +160,8 @@
   "dependencies": {
     "@codemirror/lang-markdown": "6.5.1",
     "@codemirror/theme-one-dark": "6.1.3",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@radix-ui/react-collapsible": "1.1.20",
     "@radix-ui/react-dialog": "1.1.23",
     "@radix-ui/react-dropdown-menu": "2.1.24",

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)
 -- ─────────────────────────────────────────────────────────────────────────────