@gmickel/gno 1.44.0 → 1.45.0

package/assets/skill/SKILL.md

@@ -62,6 +62,9 @@ the matching recipe, then run the commands it names.
 | Summarize a source                  | `recipes/source-summary.md`          | Source-summary note with provenance verified  |
 | Preserve an idea                    | `recipes/idea-capture.md`            | Original phrasing captured and findable       |
 | Verify claims and citations         | `recipes/citation-and-provenance.md` | Claims labeled with evidence or explicit gaps |
+| File a fact that may change         | `recipes/memory-file-decision.md`    | Fact stored (add) or proposal resolved, cited |
+| Replace a stale recalled fact       | `recipes/memory-supersede-fact.md`   | Successor written, predecessor superseded     |
+| What do we know/believe about X     | `recipes/memory-scoped-recall.md`    | Current facts recalled under budget, cited    |
 
 Recipe rules:
 

package/assets/skill/recipes/memory-file-decision.md

@@ -0,0 +1,76 @@
+# Memory: File A Decision
+
+Use this recipe when a conversation settles one fact that may later change (a
+decision, a preference, a standing rule) and the agent should be able to
+recall it next session. Documents and long notes go through
+`recipes/capture-and-file.md`; this recipe stores one fact.
+
+## Inputs
+
+- The fact, in one or two sentences, as it should be recalled later.
+- One to eight explicit scopes (`project:gno`, `family`, `client/acme`).
+  There is no implicit global scope; every call names its scopes.
+- Source evidence when known (a meeting, a message, a URL — never a `gno://`
+  URI, which the fence rejects as GNO-derived).
+- The memory-managed collection when more than one is configured.
+
+## Workflow
+
+1. Recall first so a fact that already exists is not filed twice.
+
+```bash
+gno recall "<the topic>" --scope <scope> --json > /tmp/recall.json
+```
+
+2. Propose the fact. Without a decision `remember` writes nothing and returns
+   `outcome: "candidates"` with likely and weak matches from the same scopes.
+
+```bash
+gno remember "<fact>" --scope <scope> --json
+```
+
+3. Decide from the candidates. GNO never adjudicates a likely match; the
+   caller does.
+   - No match, or the match is a different fact: add.
+   - A match says the same thing: stop; `outcome: "existing"` means nothing
+     is written and the record is already current.
+   - A match is the same fact with stale content: switch to
+     `recipes/memory-supersede-fact.md`.
+
+```bash
+gno remember "<fact>" --scope <scope> --add \
+  --source "<where this came from>" --receipt /tmp/recall.json --json
+```
+
+4. Read the result. `outcome: "added"` plus `sync.status: "completed"` means
+   the fact file exists and is retrievable now; a `failed` sync means the
+   file exists and the index lags (`gno update <collection>`).
+
+5. Verify by recalling it back and cite the returned `uri`.
+
+```bash
+gno recall "<distinctive phrase>" --scope <scope>
+```
+
+## Guardrails
+
+- Store what the user said or decided, not GNO's own recall output. Pass the
+  recall receipt (`--receipt`) so a recalled span cannot be re-filed as new;
+  a paraphrase without lineage cannot be fenced, so do not paraphrase
+  recalled facts into new ones.
+- Never store a fact without an explicit `--add`; a question alone is
+  read-only, and `remember` without a decision is a proposal.
+- Scopes are visibility, not access control. Pick the scope the fact belongs
+  to; use a shared scope name only when several callers agree on it.
+- `remember` works only on a collection with `memoryManaged: true`; other
+  collections fail with `MEMORY_COLLECTION_UNMANAGED`. Do not fall back to
+  `gno capture` for a fact that may change.
+- Keep the text self-contained; recall returns the fact without the
+  conversation that produced it.
+
+## Done
+
+- `outcome: "added"` with a `gno://` URI, or `existing` with the current
+  record.
+- Recall in the same scope returns the fact.
+- The user's wording, scopes, and source are preserved.

package/assets/skill/recipes/memory-scoped-recall.md

@@ -0,0 +1,66 @@
+# Memory: Scoped Recall
+
+Use this recipe for "what do we know / what did we decide / what does the
+user believe about X" questions, before document search and before answering
+from general knowledge. Recall returns only current facts, under a budget,
+with `gno://` cites.
+
+## Inputs
+
+- The question, as a short query.
+- The scopes the answer may draw from (`project:gno`, `family`,
+  `client/acme`). Every call names its scopes; there is no implicit global
+  scope.
+- Budget when the default (8 facts, 512 tokens) is too much or too little.
+- The memory-managed collection when more than one is configured.
+
+## Workflow
+
+1. Recall in the narrowest scope that should hold the answer.
+
+```bash
+gno recall "<question>" --scope <scope> --json
+gno recall "<question>" --scope <scope-a> --scope <scope-b> --max-facts 3 --max-tokens 256 --json
+```
+
+Visibility is any-intersection: a fact is returned when at least one of
+the call's scopes appears on it. Widen by adding scopes, not by dropping
+the flag.
+
+2. Read the response.
+   - `facts[]`: `uri`, `text`, `scopes`, `contentHash`, `supersedes`, `score`.
+     Superseded records never appear.
+   - `budget.omitted` > 0: facts matched but did not fit. Narrow the query
+     or raise the budget.
+   - Empty `facts` plus a `hint`: nothing is stored in scope yet. Say so;
+     the hint names `gno remember` for when the user wants to store one.
+   - `retrieval.mode: "lexical"`: the collection has no cached embeddings, so
+     the query matched every term. Rephrase to the fact's own words, or embed
+     the collection (`gno embed <collection>`) for question-shaped queries.
+
+3. Answer from the facts and cite each by its `gno://` URI. When memory is
+   silent or stale, fall through to `gno search` / `gno query` on the
+   documents; memory answers "what we believe", documents answer "what the
+   sources say".
+
+4. Keep the JSON if a write may follow. Its `receipt` is what `gno remember
+--receipt` fences against, and its `contentHash` is what a supersede
+   requires (`recipes/memory-supersede-fact.md`).
+
+## Guardrails
+
+- Recalled spans are context, not new facts. Never feed recall output back
+  into `gno remember`; the fence catches exact replays with a receipt, not
+  paraphrases.
+- Do not widen to every scope by habit. Scopes partition visibility; a recall
+  scoped to `project:other` should not surface family facts.
+- `recall` reads memory-managed collections only; ordinary notes are not
+  facts. Use the document ladder for them.
+- Respect the response's `egressLineage`; derived output inherits the
+  strictest policy across the returned facts.
+
+## Done
+
+- Facts cited by `gno://` URI, or an explicit "nothing stored in scope".
+- Omitted facts acknowledged when `budget.omitted` is non-zero.
+- Recall JSON kept when a remember or supersede follows.

package/assets/skill/recipes/memory-supersede-fact.md

@@ -0,0 +1,68 @@
+# Memory: Supersede A Stale Fact
+
+Use this recipe when a recalled fact is no longer true and a newer statement
+replaces it. Facts are replaced, never edited in place and never deleted by
+the memory contract.
+
+## Inputs
+
+- The stale fact's `uri` and `contentHash`, taken from a recall.
+- The replacement text.
+- The same scopes the stale fact is visible in.
+- Source evidence for the change when known.
+
+## Workflow
+
+1. Recall the current fact and keep the JSON; it carries the predecessor's
+   `uri`, `contentHash`, and the receipt.
+
+```bash
+gno recall "<the topic>" --scope <scope> --json > /tmp/recall.json
+```
+
+2. Confirm the match is the same fact with stale content, not a different
+   fact. Two facts that both hold get an add, not a supersede.
+
+3. Supersede, naming the predecessor and its hash.
+
+```bash
+gno remember "<replacement text>" --scope <scope> \
+  --supersede <uri> --predecessor-hash <contentHash> \
+  --source "<what changed and where that is recorded>" \
+  --receipt /tmp/recall.json --json
+```
+
+The scriptable spelling `--decision supersede --predecessor <uri>` means
+the same thing.
+
+4. Read the result. `outcome: "superseded"` returns the successor record with
+   `supersedes: [<uri>]`.
+   - `MEMORY_PREDECESSOR_HASH_MISMATCH`: the fact changed since the recall.
+     Recall again and decide against the current text.
+   - `MEMORY_SUPERSEDE_CONFLICT` (exit 4): another writer superseded it
+     first. Recall again; the successor may already say what you meant.
+
+5. Verify: recall returns the successor and not the predecessor.
+
+```bash
+gno recall "<distinctive phrase>" --scope <scope>
+```
+
+## Guardrails
+
+- Never supersede without the `contentHash` from a recall; the hash is what
+  proves the replacement targets the fact the agent actually read.
+- The replacement must be a new statement. Re-storing the recalled text is
+  fenced (`MEMORY_FENCED_REPLAY`) when the receipt is presented; a
+  paraphrase without lineage is not, so do not rephrase the old fact as a
+  "new" one.
+- Superseded facts stay on disk and in ordinary `gno search`; only `recall`
+  excludes them. To remove a file, the user deletes it and runs
+  `gno update`; the contract has no delete.
+- Do not chain supersedes speculatively; one recalled fact, one decision.
+
+## Done
+
+- `outcome: "superseded"` with a successor URI carrying `supersedes`.
+- Recall in scope returns the successor only.
+- A conflict or hash mismatch ended in a fresh recall, not a retry loop.

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

@@ -0,0 +1 @@
+ea5867ff2927a15524f4d5167c7ee9ee8a530b3604fefad886ec0327af7185d8  gno-browser-clipper-v1.45.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.44.0"
+  "version": "1.45.0"
 }

package/package.json

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

package/src/cli/commands/agents/block.ts

@@ -17,7 +17,7 @@ import { CliError } from "../../errors.js";
 // ─────────────────────────────────────────────────────────────────────────────
 
 /** Version of the protocol block content. Bump on any content change. */
-export const BLOCK_VERSION = 2;
+export const BLOCK_VERSION = 3;
 
 /** Stable across block versions — never change these once shipped. */
 export const BEGIN_MARKER = "<!-- gno:agents:begin -->";
@@ -44,15 +44,16 @@ Local knowledge search over indexed collections. Source files are the truth; the
 Ladder — scope to a collection first (\`--collection <name>\`):
 
 1. Exact term/identifier/quote/error: \`gno search "<text>"\`
-2. Entity or known document: \`gno query "<question>" --fast -n 10\`
-3. Multi-document evidence for a goal: \`gno context build "<goal>" --budget 12000\`
-4. Change/dependency questions: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
-5. Generated factual answer: \`gno ask "<question>" --verify\` (abstention is valid)
-6. Expected document missing: reformulate + re-check collection scope (\`gno query diagnose "<query>" --target <doc>\`) before any grep fallback.
+2. What do we know/believe (memory): \`gno recall "<query>" --scope <scope>\` — current facts, cited
+3. Entity or known document: \`gno query "<question>" --fast -n 10\`
+4. Multi-document evidence: \`gno context build "<goal>" --budget 12000\`
+5. Change/dependency questions: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
+6. Generated factual answer: \`gno ask "<question>" --verify\` (abstention is valid)
+7. Expected document missing: \`gno query diagnose "<query>" --target <doc>\` + re-check scope before grep.
 
-Writing: retrieve first — a question alone is read-only. Edit an existing canonical note in its source file; \`gno capture\` creates genuinely new notes (collection, title/path, source kind, provenance) — never an update API. After writes: reindex the collection, verify retrieval.
+Writing: retrieve first — a question alone is read-only. Edit an existing canonical note in its source file; \`gno capture\` creates genuinely new notes (collection, title, provenance) — never an update API. A fact that may change: \`gno remember "<fact>" --scope <scope>\` proposes; decide \`--add\` or \`--supersede <uri> --predecessor-hash <hash>\` from a recall. Recalled spans are context, not new facts: pass the receipt (\`--receipt\`). After writes: reindex the collection, verify retrieval.
 
-Cite with gno:// URIs. Advanced retrieval (structured queries, filters, backlinks, similar, capture recipes) lives in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
+Cite with gno:// URIs. Advanced retrieval (structured queries, filters, backlinks) and memory recipes live in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
 }
 
 /** SHA-256 hex digest of the body, truncated for the stamp line. */

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

@@ -1 +0,0 @@
-31a5cf0632f64360093ef6184708a77244d0e65e6d344d3ba6e11902fcab12b1  gno-browser-clipper-v1.44.0.zip