@gmickel/gno 2.5.1 → 2.7.0

package/README.md

@@ -60,6 +60,7 @@ Everything runs on your machine. Zero telemetry. The three network boundaries ar
 - your knowledge is split across Markdown, code, PDFs, Office files, and exported mail or transcripts
 - you want one retrieval layer for the CLI, the browser, MCP, and a Bun/TypeScript SDK
 - you want your coding agent to have a real memory without shipping your docs to a cloud API
+- you want to search what you and your coding agents said in past sessions, kept apart from your curated notes
 - you need to prove, later, which bytes supported a conclusion
 
 ## Two minutes, end to end
@@ -118,7 +119,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 **Start here** · [Quick Start](#quick-start) · [Installation](#installation) · [Agent Integration](#agent-integration) · [Search Modes](#search-modes)
 
-**Surfaces** · [Web UI](#web-ui) · [Omarchy Plugin](#omarchy-plugin) · [REST API](#rest-api) · [SDK](#sdk) · [Daemon Mode](#daemon-mode) · [Publish to gno.sh](#publish-to-gnosh)
+**Surfaces** · [Agent Sessions](#agent-sessions) · [Web UI](#web-ui) · [Omarchy Plugin](#omarchy-plugin) · [REST API](#rest-api) · [SDK](#sdk) · [Daemon Mode](#daemon-mode) · [Publish to gno.sh](#publish-to-gnosh)
 
 **Under the hood** · [How It Works](#how-it-works) · [Features](#features) · [Local Models](#local-models) · [Fine-Tuned Models](#fine-tuned-models) · [Architecture](#architecture) · [Development](#development)
 
@@ -138,12 +139,18 @@ See the [guide](docs/COMPILED-CONTEXT.md).
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.5.1**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.7.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 
 > Full release history: [CHANGELOG.md](./CHANGELOG.md)
 
+- **Agent session search** (unreleased): `gno sessions` imports selected local
+  Codex, Claude Code, OpenClaw, and Hermes conversations into a dedicated,
+  redacted archive with speaker labels and provenance. Imports are manual
+  by default; an opt-in Claude Code SessionEnd hook and daemon schedule can
+  keep the archive current. Search runs on the archive's own config/index
+  pair. See [Agent Sessions](docs/SESSIONS.md).
 - **Cheap peek snapshot**: `gno peek --json` and MCP `gno_peek` return a
   model-free `peek@1.0` snapshot (document/collection counts, embedding backlog,
   10 recent docs with `docid` and `absPath`, pid-file serve detection).
@@ -712,9 +719,10 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 33 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+GNO exposes 37 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
 including the core retrieval tools below. Starting MCP with `--enable-write`
-adds 18 opt-in mutation tools, for 51 total.
+adds 21 opt-in mutation tools and the read-only `gno_request_status` lookup,
+for 59 total.
 
 | Tool                 | Description                                     |
 | :------------------- | :---------------------------------------------- |
@@ -757,6 +765,50 @@ enables mutation tools.
 
 ---
 
+## Agent Sessions
+
+Make past conversations with Codex, Claude Code, OpenClaw, and Hermes
+searchable without mixing them into your curated notes. GNO reads the local
+session stores (never writes to them), keeps human and assistant turns
+apart, redacts common credential shapes, and writes one sanitized JSONL file
+per thread into an archive you own. Nothing is imported until you ask.
+
+```bash
+# Preview what is on this machine (imports nothing)
+gno sessions discover
+
+# One dedicated config + named index for the archive
+gno --config ~/gno-sessions/archive.yml --index sessions \
+  sessions init --archive ~/gno-sessions/archive --collection sessions-work
+gno --config ~/gno-sessions/archive.yml --index sessions \
+  sessions source add codex --harness codex --path ~/.codex/sessions --collection sessions-work
+
+# Dry run, then import (rerun any time; unchanged sessions are skipped)
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex --dry-run
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex
+
+# Search what people said, in one harness
+gno --config ~/gno-sessions/archive.yml --index sessions \
+  query "why did we pick sqlite" --category harness/codex --author human
+
+# Optional: keep it current (off until you enable it; imports run in gno daemon)
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation set codex --source codex
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation enable codex --schedule --cadence 1h
+gno --config ~/gno-sessions/archive.yml --index sessions daemon --detach
+```
+
+Imported turns are evidence, not facts: assistant turns stay labelled as
+assistant output, and nothing is promoted to `gno remember` automatically.
+Automation is opt-in per profile: a Claude Code SessionEnd hook or a daemon
+schedule marks work pending and `gno daemon` on the archive imports it through
+the same importer; nothing installs or starts a service. Status, import,
+automation runs, and receipts are also available through MCP, REST, the SDK,
+and a `/sessions` Web UI page on a server started with the archive pair.
+Redaction is best effort; see [Agent Sessions](docs/SESSIONS.md) for the
+support matrix, privacy boundary, recovery, and opt-in mixed retrieval.
+
+---
+
 ## Web UI
 
 Visual dashboard for search, browsing, editing, and AI answers. Right in your browser.
@@ -777,6 +829,7 @@ Open `http://localhost:3000` to:
 - **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).
+- **Agent sessions**: on a server started with a session-archive config/index pair, `/sessions` manages sources, previews and runs manual imports, and searches sessions with Human/Assistant badges. See [Agent Sessions](docs/SESSIONS.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).
@@ -1076,10 +1129,11 @@ graph TD
 | **Web UI**           | Visual dashboard for search, browse, edit, and AI Q&A                                       |
 | **REST API**         | HTTP API for custom tools and integrations                                                  |
 | **Multi-Format**     | Markdown, PDF, Office, JSONL, EML/MBOX, ICS, transcript, and browser exports                |
+| **Agent Sessions**   | Manual, redacted import of local coding-agent conversations into a separate archive         |
 | **Local LLM**        | AI answers via llama.cpp, no API keys                                                       |
 | **Remote Inference** | Optional HTTP endpoints for embedding, reranking, expansion, and generation                 |
 | **Privacy First**    | Fail-closed per-collection egress policy; no telemetry; explicit network use                |
-| **MCP Server**       | 10 automatic client targets; 32 read-only tools, 50 with writes enabled                     |
+| **MCP Server**       | 10 automatic client targets; 37 read-only tools, 59 with writes enabled                     |
 | **Integrity Audits** | Offline link, declared-provenance, and freshness reports with stable IDs                    |
 | **Knowledge Delta**  | Bounded metadata history, structural diffs, and dependency impact paths                     |
 | **Context Capsules** | Deterministic evidence bundles plus saved-file freshness reverification                     |
@@ -1087,6 +1141,7 @@ graph TD
 | **Private Replay**   | Opt-in local traces, explicit qrels, and read-only ranking comparison                       |
 | **Verified Setup**   | Exact lexical activation proof plus portable project-local profiles                         |
 | **Browser Clipper**  | Explicit selection/Reader capture through visible loopback pairing                          |
+| **Safe Retries**     | Opt-in request IDs: retried captures, facts, and saves replay instead of writing twice      |
 | **Collections**      | Organize sources with patterns, contexts, and <code>local_only / lan / remote</code> policy |
 | **Tag Filtering**    | Frontmatter tags with hierarchical paths, filter via `--tags-any`/`--tags-all`              |
 | **Note Linking**     | Wiki links, backlinks, related notes, cross-collection navigation                           |

package/assets/skill/README.md

@@ -132,6 +132,9 @@ walk the model through:
 - private retrieval traces/replay and Knowledge Delta inspection
 - project affinity, explainable content boosts, and collection egress policy
 - JSONL, mail, calendar, transcript, and browser-export source adapters
+- manual agent-session import into a separate archive, opt-in automation
+  (Claude Code SessionEnd hook, daemon schedule), and citing session turns as
+  evidence rather than facts
 - provenance-aware browser clipping and typed second-brain capture recipes
 - tagging, contexts, and per-collection embedding models
 - publishing notes as gno.sh reader snapshots (`publish export`)
@@ -145,7 +148,8 @@ progressive disclosure — the model only pulls them when it needs them:
 - [mcp-reference.md](mcp-reference.md) — MCP tool and resource contract
 - [examples.md](examples.md) — end-to-end usage patterns
 - [recipes/](recipes/) — task-shaped second-brain workflows for lookup,
-  capture, meetings, email context, source summaries, ideas, and citations
+  capture, meetings, email context, source summaries, ideas, citations,
+  memory, and past agent sessions
 
 ## Agent tooling contract
 

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gno
-description: Search local documents, files, notes, and knowledge bases. Index directories, search with BM25/vector/hybrid, get AI answers with citations. Use when user wants to search files, find documents, query notes, look up information in local folders, index a directory, set up document search, build a knowledge base, needs RAG/semantic search, or wants to start a local web UI for their docs.
+description: Search local documents, files, notes, and knowledge bases. Index directories, search with BM25/vector/hybrid, get AI answers with citations. Use when user wants to search files, find documents, query notes, look up information in local folders, index a directory, set up document search, build a knowledge base, needs RAG/semantic search, wants to start a local web UI for their docs, or asks what was said in past coding-agent sessions.
 allowed-tools: Bash(gno:*) Read
 ---
 
@@ -26,6 +26,7 @@ network boundaries.
 - User asks about **backlinks, wiki links, or related notes**
 - User wants to **visualize document connections** or see a **knowledge graph**
 - User wants to **export a note or collection for gno.sh publishing**
+- User asks what was **said or decided in past agent sessions** (Codex, Claude Code, OpenClaw, Hermes)
 
 ## Quick Start
 
@@ -65,6 +66,7 @@ the matching recipe, then run the commands it names.
 | 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    |
+| What was said/decided in a session  | `recipes/session-evidence-lookup.md` | Turns cited with speaker; proposals labelled  |
 
 Recipe rules:
 
@@ -92,6 +94,7 @@ Recipe rules:
 | **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         |
+| **Sessions** | `sessions discover/init/source add/source remove/import/status/prune/automation`                           | Agent-session archive: manual import, opt-in hook/schedule automation    |
 | **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                                   |
@@ -127,8 +130,9 @@ Open without fetching content via `gno get`:
   `#anchor`). Take `serveUrl` from peek `serve.url` when `serve.running` is
   true.
 - **Source file**: peek `recent[].absPath`, or search `--json`
-  `results[].source.absPath`. If `absPath` is absent, show the URI tail and
-  do not offer file-open for that row.
+  `results[].source.absPath`. If `absPath` is absent (always for remote REST
+  and HTTP MCP callers), show the URI tail and do not offer file-open for
+  that row.
 
 ## Search Modes
 
@@ -554,7 +558,8 @@ Programmatic capture uses the same receipt contract:
 
 MCP capture writes structured `source:` frontmatter, runs under the MCP write
 lock, syncs the file for FTS, and preserves legacy MCP fields (`docid`,
-`absPath`, `overwritten`, `serverInstanceId`) alongside the shared receipt. It
+`absPath` over stdio only, `overwritten`, `serverInstanceId`) alongside the
+shared receipt. It
 does not auto-embed.
 
 For an explicit browser capture, use the local unpacked Chromium clipper with
@@ -584,6 +589,77 @@ existing notes. They work only on a collection with `memoryManaged: true`.
 - Details, error codes, and the fence's paraphrase limit: `docs/MEMORY.md`,
   [cli-reference.md](cli-reference.md), [mcp-reference.md](mcp-reference.md).
 
+## Agent Sessions (separate archive)
+
+`gno sessions` imports local Codex, Claude Code, OpenClaw, and Hermes
+conversations into a dedicated archive: its own config file plus a named
+index. Broad search on the user's normal index never includes it, so search
+sessions on the archive pair, and pass both flags on every archive command:
+
+```bash
+gno sessions discover                     # preview local stores; imports nothing
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex --dry-run
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex --json
+gno --config ~/gno-sessions/archive.yml --index sessions search "postgres" --author human --tags-all project/api
+gno --config ~/gno-sessions/archive.yml --index sessions query "why sqlite" --category harness/codex
+```
+
+- Manual by default: discover, then import only when the user asks. Setup
+  (on the pair) is `sessions init --archive <dir> --collection <name>`, then
+  `sessions source add <id> --harness <h> --path <root> --collection <name>`
+  with optional repeatable `--project <prefix>=<collection>`. Keep the
+  archive outside the curated vault, one collection per privacy boundary.
+- Filters: `--author human|assistant`, tags `harness/<h>`, `role/<r>`,
+  `project/<name>`, `project-id/<hash>`, `session-kind/<k>`, `-c <collection>`.
+  Import does not embed; run `embed` on the pair for `query`/`vsearch`.
+- Reruns are incremental. `partial` receipts (`truncated_tail`,
+  `format_drift`) retry on the next import; `--limit <n>` defers the rest;
+  `SESSIONS_BUSY` means another import runs; `SESSIONS_BINDING_MISMATCH`
+  means the config and index were not passed together.
+- Session turns are evidence, not facts. A human turn is what the person
+  said; an assistant turn is a proposal, never the user's decision. Cite by
+  `gno://` URI (keep `?index=sessions`). Nothing is promoted to
+  `remember`/`recall` automatically; store a fact only when asked, with the
+  turn's URI as `--source`. Workflow: `recipes/session-evidence-lookup.md`.
+- Automation is opt-in and only on the user's explicit request; installing
+  this skill, GNO, or MCP never enables it.
+  `sessions automation set <p> --source <id>` creates a profile (nothing
+  enabled), `preview <p>` shows the exact hook command, settings file, and
+  daemon prerequisite, and `enable <p> --hook claude-code` or
+  `enable <p> --schedule --cadence 30m` switches one trigger on.
+  Only the Claude Code SessionEnd hook exists; other harnesses use a
+  schedule. Triggers only mark work pending: imports run in `gno daemon` on
+  the archive pair (never `gno serve`) or with `sessions automation run <p>`.
+- Check automation with `sessions status` (`automation` block: `state`,
+  `pending`, `lastRun`, `lastSuccessAt`, `recovery`). A hook that says
+  `accepted` has not archived anything yet; `not running: no daemon` means
+  start the daemon or run the profile. Repair a missing hook entry by
+  re-running `enable --hook claude-code`; pause with `disable <p>`,
+  uninstall with `remove <p>` (only GNO's own entry is touched; archives
+  stay). `GNO_SESSIONS_HOOKS=off` silences installed hooks.
+
+## Retry-Safe Writes (request IDs)
+
+For capture, `remember --add`/`--supersede`, and REST document saves, generate
+one fresh ID (a UUID) per write intent and save it before sending: CLI
+`--request-id <id>`, MCP/REST/SDK `requestId`.
+
+```bash
+gno capture "Launch moved to Oct 3" --request-id 7d0c6f2e-... --json
+gno request-status 7d0c6f2e-... --json   # after a timeout or lost response
+```
+
+- Check before retrying (`gno request-status <id>`, MCP `gno_request_status`,
+  REST `GET /api/requests/:requestId`, SDK `client.requestStatus(id)`):
+  `committed` = done, use `result`, do not resend; `pending` or `not_found` =
+  resend the identical call with the same ID; `expired` = it already ran.
+- Never reuse an ID for a changed payload (`REQUEST_ID_CONFLICT`); a new
+  intent gets a new ID.
+- `REQUEST_RECOVERY_CONFLICT`, `CONFLICT`, or a predecessor-hash mismatch:
+  re-read (`gno get` / `gno recall`) and decide again; never force-overwrite.
+- A request ID is not a recall `receipt`: the receipt fences recalled text,
+  the ID identifies one write for retries. Details: [cli-reference.md](cli-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

@@ -117,9 +117,15 @@ gno collection clear-embeddings <name> [--all] [--json]
 ### gno embed
 
 ```bash
-gno embed [collection] [--collection <name>] [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
+gno embed [collection] [--collection <name>] [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--new-partition]
 ```
 
+Switching `GNO_LLAMA_GPU`, Bun version or thread count resumes the existing
+vector partition when a measured sample of stored chunks matches. If it does
+not, embed refuses to build a separate partition without `--new-partition`
+(`--yes` alone never confirms); queries from that runtime fall back to lexical
+retrieval with a `vector_runtime_incompatible` warning.
+
 ## Indexing
 
 ### gno update
@@ -150,7 +156,7 @@ gno index [options]
 Generate embeddings only.
 
 ```bash
-gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
+gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--new-partition]
 ```
 
 ## Project Profiles
@@ -205,6 +211,8 @@ Important behavior:
 - `--json` returns a capture receipt with separate write, sync, and embed status.
 - Capture syncs the file into FTS but does not imply embedding unless
   `embed.status` is `completed`.
+- `--request-id <id>` makes a retry safe; see
+  [Retry-safe writes](#retry-safe-writes-request-ids).
 
 ## Memory
 
@@ -236,6 +244,9 @@ gno remember "..." --scope family --scope shared --collection memory --add --sou
   `--derived-from gno://...` is rejected. `--source <text>` stores evidence.
 - `--caller` / `--session` default from `$GNO_MEMORY_CALLER` /
   `$GNO_MEMORY_SESSION`, then `cli:<user>` / `ppid:<pid>`.
+- `--request-id <id>` needs `--add` or `--supersede`; a candidates-only call
+  with an ID is rejected `REQUEST_ID_INVALID`. It is unrelated to
+  `--receipt`.
 
 ### gno recall
 
@@ -254,6 +265,124 @@ gno recall "kindergarten" --scope family --max-facts 3 --max-tokens 256 --json >
   lexical with the reason; recall never downloads a model.
 - Nothing in scope prints the self-teaching line naming `gno remember`.
 
+## Sessions
+
+Manual import (plus opt-in automation) of local agent conversations (Codex,
+Claude Code, OpenClaw, Hermes) into a dedicated archive: one config file with a `sessions` block
+plus one named index. Every command except `discover` passes both flags;
+the archive config with another index (or the archive index with another
+config) fails with `SESSIONS_BINDING_MISMATCH`. Full guide: `docs/SESSIONS.md`.
+
+```bash
+gno sessions discover [--json]            # preview local stores; never imports
+gno --config ~/gno-sessions/archive.yml --index sessions sessions init --archive ~/gno-sessions/archive --collection sessions-work
+gno --config ~/gno-sessions/archive.yml --index sessions sessions source add codex --harness codex --path ~/.codex/sessions --collection sessions-work --project ~/work/api=sessions-api
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex --dry-run
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source codex --limit 200 --json
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import /abs/session.jsonl --collection sessions-work --format codex
+gno --config ~/gno-sessions/archive.yml --index sessions sessions status --json
+gno --config ~/gno-sessions/archive.yml --index sessions sessions prune --source codex [--apply]
+gno --config ~/gno-sessions/archive.yml --index sessions sessions source remove codex   # archive kept
+
+# Opt-in automation (off until enabled; imports run in `gno daemon` on the pair)
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation set claude --source claude-code [--cadence 30m] [--limit 200] [--retries 3]
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation preview claude [--json]
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation enable claude --hook claude-code [--settings <abs settings.json>]
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation enable claude --schedule --cadence 30m
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation run claude [--json]
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation disable claude [--hook] [--schedule]
+gno --config ~/gno-sessions/archive.yml --index sessions sessions automation remove claude
+gno --config ~/gno-sessions/archive.yml --index sessions daemon --detach
+```
+
+- `--harness`/`--format`: `codex`, `claude-code`, `openclaw`, `hermes`. Paths
+  are absolute. `--collection` is for path imports and rejected with
+  `--source`.
+- Receipt `status`: `complete`, `partial` (incomplete, failed, unsupported,
+  or deferred units; exit 0), `failed` (exit 2), `nothing_to_do`. Reasons
+  include `truncated_tail`, `format_drift`, `snapshot_read_failed`,
+  `mixed_domain` (quarantined thread), `over_limit`. Reruns are incremental
+  and retry incomplete units. Exit 4 = `SESSIONS_BUSY`.
+- Import does not embed: `gno --config … --index sessions embed`.
+- Automation: only the Claude Code SessionEnd hook is supported
+  (`SESSIONS_UNSUPPORTED_INTEGRATION` otherwise); cadence `<n>s|m|h|d`, min
+  `1m`, elapsed. `sessions hook claude-code --profile <id>` is what the hook
+  runs: it prints `accepted (… pending, not yet archived …)`, `skipped`, or
+  `not accepted` (exit 2) and never imports. `sessions status` shows the
+  `automation` block with `state`, `recovery`, and `not running: no daemon`
+  when no daemon on the pair is ticking. Run outcomes: `complete`,
+  `up_to_date`, `partial`, `failed`, `not_started`.
+- Search with the normal commands on the pair: `--author human|assistant`,
+  `--category harness/<h>`, `--tags-all role/<r>,project/<name>`,
+  `-c <collection>`. `--since`/`--until` use import time.
+
+## Retry-safe writes (request IDs)
+
+An optional request ID lets a write be retried after a lost response
+(timeout, dropped connection, crash, restart) without a duplicate capture, a
+double supersede, or overwriting a newer document edit. Calls without an ID
+behave as before.
+
+| Write                  | CLI                                        | MCP / REST / SDK field                                                     |
+| ---------------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
+| Capture                | `gno capture ... --request-id <id>`        | `gno_capture`, `POST /api/capture`, `client.capture` `requestId`           |
+| Remember add/supersede | `gno remember ... --add --request-id <id>` | `gno_remember`, `POST /api/memory/remember`, `client.remember` `requestId` |
+| Document save/tags     | none                                       | REST `PUT /api/docs/:id` body `requestId`                                  |
+
+The browser-clipper route `POST /api/capture/clip` keeps its
+`Idempotency-Key` header and rejects `requestId`.
+
+IDs are 1-128 characters of letters, digits, `.`, `_`, `:`, `-`, starting with
+a letter or digit; a UUID works.
+
+```bash
+ID=$(uuidgen)                                   # one ID per write intent; save it first
+gno capture "Launch moved to Oct 3" --request-id "$ID" --json
+# response lost? check before retrying:
+gno request-status "$ID" --json
+```
+
+### gno request-status
+
+`gno request-status <request-id> [--json]` (MCP `gno_request_status`
+`{ requestId }`, REST `GET /api/requests/:requestId`, SDK
+`client.requestStatus(id)`). Read-only and content-free: `requestId`,
+`status`, `operation` (`capture` | `remember` | `document.update`),
+timestamps, and for committed requests a `result` with `uri`, `docid`, and
+`contentHash` (or `sourceHash` for a document save).
+
+| `status`    | Meaning                                          | Next step                                  |
+| ----------- | ------------------------------------------------ | ------------------------------------------ |
+| `committed` | The write finished                               | Use `result`; do not resend                |
+| `pending`   | Accepted and written but not finished            | Resend the identical call with the same ID |
+| `not_found` | Nothing accepted under this ID                   | Resend the identical call with the same ID |
+| `expired`   | Ran before; full receipt compacted after 30 days | Do not resend; it will not run again       |
+
+Retry rules:
+
+- Identical retry of a committed request replays the stored outcome with
+  `request.replayed: true`; nothing is written again. Retrying a `pending`
+  request with the same ID finishes the recorded write instead of writing
+  again. Retrying with a new ID is a new write; do not.
+- Successful writes sent with an ID include
+  `request: { requestId, status, replayed, committedAt }`; CLI text prints
+  `Request: <id> committed`.
+- Never reuse an ID for a changed payload, destination, revision, or
+  predecessor: `REQUEST_ID_CONFLICT`. New intent, new ID.
+- `REQUEST_RECOVERY_CONFLICT` (the interrupted target changed on disk),
+  `CONFLICT` (document revision moved), `MEMORY_PREDECESSOR_HASH_MISMATCH`, or
+  `MEMORY_SUPERSEDE_CONFLICT`: re-read with `gno get` or `gno recall` and
+  decide again. Never force-overwrite.
+- `REQUEST_PENDING` (exit 4): another caller is still executing it; retry the
+  same ID later. `REQUEST_EXPIRED`: do not resend.
+- A rejected write (validation, stale hash, conflict) records nothing, so
+  status reads `not_found` and a same-ID retry re-evaluates current state.
+- Request IDs are not recall receipts: `--receipt` / `receipt` fences recalled
+  text; `requestId` identifies one write for retries.
+- Other codes: `REQUEST_ID_INVALID`, `REQUEST_CAPACITY_EXHAUSTED`,
+  `REQUEST_LEDGER_UNAVAILABLE` (all rejected before any write). CLI errors
+  carry the code in `details.requestCode`.
+
 ## Search Commands
 
 ### gno search
@@ -734,6 +863,7 @@ Vector index maintenance. Use when `gno similar` returns empty despite embedding
 ```bash
 gno vec sync      # Fast incremental sync
 gno vec rebuild   # Full rebuild
+gno vec drop <partition>   # Drop an abandoned shadow partition (id prefix from gno status)
 ```
 
 | Option   | Description |

package/assets/skill/examples.md

@@ -362,6 +362,36 @@ gno query "auth" --tags-all security,reviewed
 gno ask "deployment steps" -c work --tags-any devops --answer
 ```
 
+## Agent Sessions
+
+### Make past agent sessions searchable
+
+```bash
+# Preview local session stores (imports nothing)
+gno sessions discover
+
+# Dedicated archive: its own config file + named index
+gno --config ~/gno-sessions/archive.yml --index sessions sessions init --archive ~/gno-sessions/archive --collection sessions-work
+gno --config ~/gno-sessions/archive.yml --index sessions sessions source add claude --harness claude-code --path ~/.claude/projects --collection sessions-work
+
+# Dry run, then import; rerun later to pick up new turns
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source claude --dry-run
+gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source claude
+```
+
+### Find a past decision
+
+```bash
+# What the person said, in one project
+gno --config ~/gno-sessions/archive.yml --index sessions search "retry budget" --author human --tags-all project/api
+
+# What an agent proposed, in one harness
+gno --config ~/gno-sessions/archive.yml --index sessions search "retry budget" --author assistant --category harness/codex
+
+# Read the turn (keep ?index=sessions on the URI)
+gno --config ~/gno-sessions/archive.yml --index sessions get "gno://sessions-work/.gno/records/...?index=sessions"
+```
+
 ## Tips
 
 ### Search Modes

package/assets/skill/mcp-reference.md

@@ -156,7 +156,8 @@ CLI-only.
 `GNO_MCP_ENABLE_WRITE=1`. It writes quick notes with structured `source:`
 frontmatter and returns the same provenance receipt shape as CLI, REST, and SDK
 capture, plus legacy MCP fields (`docid`, `absPath`, `overwritten`,
-`serverInstanceId`).
+`serverInstanceId`). `absPath` is stdio-only: HTTP MCP callers never receive
+host paths and address the note by `uri` + `relPath`.
 
 `presetId` accepts `blank`, `project-note`, `research-note`, `decision-note`,
 `prompt-pattern`, `source-summary`, `idea-original`, `person`,
@@ -195,6 +196,58 @@ transport session, never from tool arguments.
   rejected (`MEMORY_FENCED_DERIVED`). Optional `source` stores evidence.
 - Writes sync for FTS before returning and do not auto-embed.
 
+## Sessions
+
+`gno_sessions_status` (read), `gno_sessions_import` and
+`gno_sessions_automation_run` (write, need `--enable-write`) are in the
+`full` profile only and work on a server started with the session-archive
+pair:
+
+```bash
+gno --config ~/gno-sessions/archive.yml --index sessions mcp --enable-write
+```
+
+- `gno_sessions_status` takes no arguments and lists archive collections,
+  registered sources (IDs, availability, unit counts), and the `automation`
+  block (daemon state, per-profile state, pending, last run, last success,
+  recovery), no host paths.
+- `gno_sessions_automation_run` takes `profileId` only and runs a configured
+  profile now; it cannot enable hooks or schedules or add sources. Enabling
+  automation is a local owner action (`gno sessions automation enable`).
+- `gno_sessions_import` takes `sourceId` plus optional `dryRun` and `limit`;
+  `paths` and other keys are rejected, and there is no MCP discovery. Returns
+  the import receipt; `partial` is retried by the next call. It does not
+  embed.
+- Search the imported turns with `gno_search` / `gno_query` on the same
+  server (filters `author`, `categories`, `tagsAll`); cite by `gno://` URI.
+  A human turn is what the person said, an assistant turn a proposal.
+  Nothing becomes a `gno_remember` fact unless the user asks.
+
+## Retry-Safe Writes
+
+`gno_capture` and `gno_remember` (with `decision`) accept an optional
+`requestId`. Generate one fresh ID (a UUID) per write intent and keep it
+before calling.
+
+- After a timeout or lost response, call `gno_request_status` with
+  `{ requestId }` before retrying. It is read-only and registered with
+  `--enable-write` on the `full` profile (not in `core`).
+- `committed`: use `result` (`uri`, `docid`, `contentHash`); do not resend.
+  `pending` or `not_found`: resend the identical call with the same
+  `requestId`. `expired`: it already ran; do not resend.
+- An identical retry returns the stored outcome with `request.replayed: true`.
+- Never reuse a `requestId` for a changed payload (`REQUEST_ID_CONFLICT`).
+- `REQUEST_RECOVERY_CONFLICT`, `MEMORY_PREDECESSOR_HASH_MISMATCH`, or
+  `MEMORY_SUPERSEDE_CONFLICT`: re-read with `gno_get` / `gno_recall` and
+  decide again; never force-overwrite. `REQUEST_PENDING`: retry the same ID
+  later.
+- `requestId` is not the recall `receipt`: the receipt fences recalled text;
+  the ID identifies one write.
+- Over HTTP MCP, request IDs belong to the authorized identity (loopback or
+  bearer token). Rotating the token starts a new namespace: an old ID reads
+  `not_found`, so do not blindly resend an uncertain old write as new.
+- Errors arrive as tool text `CODE: message` with `structuredContent.error`.
+
 ## Uninstall
 
 ```bash

package/assets/skill/recipes/capture-and-file.md

@@ -18,6 +18,12 @@ gno capture "summary or fact" --preset decision-note --title "<title>" --json
 gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
 ```
 
+When a retry may follow a timeout or lost response, pass
+`--request-id <uuid>` (one fresh ID per note). Check
+`gno request-status <uuid>` before retrying: `committed` = already saved,
+do not resend; `pending` or `not_found` = resend the identical command with
+the same ID. Never reuse the ID for changed content.
+
 2. For an explicit browser capture, use the local Chromium clipper. The user
    selects visible top-frame text or chooses Reader mode, reviews the
    server-owned preview, then confirms the write. Pairing and capture stay

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

@@ -42,6 +42,12 @@ gno remember "<fact>" --scope <scope> --add \
   --source "<where this came from>" --receipt /tmp/recall.json --json
 ```
 
+To make a retry safe, add `--request-id <uuid>` (one fresh ID per fact,
+saved before sending). If the response is lost, run
+`gno request-status <uuid>` first: `committed` means do not resend;
+`pending` or `not_found` means resend the identical command with the same
+ID.
+
 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>`).

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

@@ -35,6 +35,11 @@ gno remember "<replacement text>" --scope <scope> \
 The scriptable spelling `--decision supersede --predecessor <uri>` means
 the same thing.
 
+Add `--request-id <uuid>` so a lost response can be retried without a double
+supersede: check `gno request-status <uuid>` first, and resend only the
+identical command with the same ID when it reports `pending` or `not_found`.
+The request ID is separate from `--receipt`.
+
 4. Read the result. `outcome: "superseded"` returns the successor record with
    `supersedes: [<uri>]`.
    - `MEMORY_PREDECESSOR_HASH_MISMATCH`: the fact changed since the recall.