@arnilo/prism 0.7.0 → 0.9.0

package/docs/run-bundle.md

@@ -0,0 +1,92 @@
+# Effective run bundle snapshots
+
+`snapshotRunBundle()` answers one question for a host harness: *what exactly ran?* It projects the inputs a
+run resolves to — prompt contributions, skills, tools, guardrails, loop, limits, model, storage kinds — into
+frozen JSON with one stable digest, so a harness registry can pin the bundle it evaluated and diff a later run
+against it. It is the inspectable half of the durable-run fingerprint: same inputs, named fields, one hash.
+
+## What it does
+
+- Reads only in-process configuration: `agent` (plus optional `AgentSessionConfig` and `RunOptions` overrides).
+- Returns frozen JSON with `schemaVersion`, a `sha256:` `digest`, and the durable `fingerprint` it corresponds to.
+- Never opens a socket, never reads a store, never resolves a credential, and never emits a store connection
+  string — only its kind and durability.
+- Never emits bodies: prompt and skill instructions are digests, tool parameters are digests.
+- Is synchronous, in-memory, and O(contributions): a 100-tool agent snapshots in well under a millisecond.
+
+`digest` is SHA-256 over the canonicalized, redacted snapshot (the `digest` field itself excluded), prefixed
+`sha256:`. Tool parameter schemas go through `canonicalizeJsonSchema()` first, so key order and `required`
+ordering cannot fake a change. Identical configuration produces an identical digest; any listed contribution
+change — a tool, a schema, a skill body, a guardrail revision, a limit, `thinkingLevel`, the loop revision, a
+request policy, a store kind — produces a different one.
+
+## When to use it
+
+- Pin the bundle in a harness/eval registry next to the run or timeline id, then diff digests across releases.
+- Explain a durable-resume failure: `fingerprint` is the value compare-and-set against stored run state, and
+  the snapshot shows *which* field moved.
+- Feed a release manifest or a support bundle: it is JSON, bounded (512 KiB), and secret-free by construction.
+
+Do not use it as a substitute for `inspectHostComposition()` (that inspects a whole composition's readiness,
+sandbox isolation, and credential references) or as a policy decision — it is a report, not a guard.
+
+## Inputs
+
+| Input | Purpose |
+| --- | --- |
+| `agent` | The agent to inspect; `agent.config` supplies tools, skills, guardrails, prompt, loop, limits, model. |
+| `config` | Optional `AgentSessionConfig`: its `store` wins over `agent.config.store` for the reported session-store kind. |
+| `run` | Optional `RunOptions`: run-level overrides (`limit`s, `thinkingLevel`, `systemPrompt`, `guardrails`, `loop`, `toolNames`, `attentionCompiler`, `providerRequestPolicies`, `runState.definitionRevision`, `effectStore`). |
+| `memory` | Optional memory store instance. Only its kind and durability are read — never its contents. |
+
+## Output
+
+```ts
+const bundle = snapshotRunBundle({ agent, run: { limits: { maxTurns: 12 }, toolNames: ["search"] } });
+
+bundle.schemaVersion;                                      // 1
+bundle.digest;                                             // "sha256:1ddd…" — pin this
+bundle.fingerprint;                                        // agentFingerprint() for durable resume
+bundle.agent;                                              // { id, definitionRevision }
+bundle.systemPrompt;                                       // { disabled, instructionsDigest, contributions: [{ id, mode, source, digest }] }
+bundle.skills;                                             // [{ name, instructionsDigest, toolNames }]
+bundle.tools;                                              // [{ name, schemaDigest, exclusive, effect }] — run.toolNames already applied
+bundle.guardrails;                                         // [{ name, stage, revision }]
+bundle.loop;                                               // { strategy, revision }
+bundle.limits;                                             // resolved ResolvedRunLimits
+bundle.model;                                              // { provider, model }
+bundle.storage;                                            // { sessionStore, checkpoints, effectStore, memory } → { kind, durable }
+```
+
+`tools` is the *effective* set: `RunOptions.toolNames` narrowing is applied, and an unknown name fails closed
+exactly as it would during the run. `storage.*.kind` comes from the store's declared `kind` or constructor name
+and is reduced to a plain token (`[a-z0-9_.-]`, ≤64 chars); anything URL-shaped is reported as `custom`, so a
+connection string can never reach a pinned artifact.
+
+## Example
+
+```ts
+import { createAgent, snapshotRunBundle } from "@arnilo/prism";
+
+const agent = createAgent({ model: { provider: "anthropic", model: "claude-sonnet-4-5" }, /* … */ });
+const bundle = snapshotRunBundle({ agent, run: { thinkingLevel: "high" } });
+
+const pinned = bundle.digest; // store with the harness artifact
+const next = snapshotRunBundle({ agent: changedAgent });
+if (next.digest !== pinned) reportFields(next, pinned); // hosts diff by field, not by digest alone
+```
+
+## Redaction and limits
+
+Every string field is passed through the host `SecretRedactor` (`RunOptions.redactor` ?? `AgentConfig.redactor`)
+before hashing and before returning, so redaction is part of the pinned digest. The snapshot refuses to exceed
+512 KiB — a bundle that large is a host wiring bug, not something to retain — and throws `TypeError` rather than
+truncating. There is no network path, no store read, and no credential resolution in this function; a store that
+throws on every method still snapshots fine.
+
+## Related APIs
+
+- [`agentFingerprint()`](durable-runs.md): the durable-resume identity this snapshot projects.
+- [`inspectHostComposition()`](host-compositions.md): composition readiness, storage durability, sandbox isolation.
+- [`ExecutionTimeline`](execution-timeline.md): what a run *did*; the snapshot is what it was *configured* with.
+- [`RunRecord`](runs-and-usage.md): the ledger row a snapshotted run leaves behind.

package/docs/runs-and-usage.md

@@ -59,12 +59,61 @@ await session.run("Summarize", {
 });
 ```
 
-Defaults are the unconfigured fence (OWASP LLM10): turns 16, provider attempts 24, tool rounds 8, tool calls 32, wall time 120 seconds, request and response bytes 8 MiB each, input tokens 40,000, output tokens 10,000, total tokens 50,000. Hard process ceilings exist only for request/response bytes (64 MiB each), so a bug cannot OOM the host through a giant provider frame; those two axes reject `null` and are charged **per frame** (request payload, provider event), not as a run-lifetime sum — a 2 MiB prompt sent forty times is 2 MiB frames, not an 80 MiB parse. Snapshots still report the cumulative `requestBytes`/`responseBytes` counters for telemetry. Every other axis is host policy (0.5.4): omit a key for the default, set a positive safe integer sized to the workload, or set `null` to disable the axis — overnight sessions raise turns/wall/tokens, and a disabled wall still honors `RunOptions.signal`. Resolution stays narrowing-only: `RunOptions.limits` may lower `AgentConfig.limits`, `null` acts as +Infinity (agent 16 + run `null` → 16), and a raised/disabled `maxTurns` lifts an omitted `maxProviderAttempts` (default 24) to at least `maxTurns` so attempts cannot undercut turns; explicitly set attempts values are lifted only when both are finite. Cumulative token counters are billed usage across the whole run, not the context window (`contextBudget` governs window compaction). For production, prefer an explicit `maxCost`: cost needs a finite non-negative amount plus one currency, and when cost is limited, absent, non-finite, or mixed-currency provider cost fails closed. Vendors that omit usage charge zero to the token counters (local/Ollama report none), so a configured `maxCost` is the fail-closed envelope for usage-less vendors.
+Defaults are the unconfigured fence (OWASP LLM10): turns 16, provider attempts 24, tool rounds 8, tool calls 32, wall time 120 seconds, request and response bytes 8 MiB each, input tokens 40,000, output tokens 10,000, total tokens 50,000. Hard process ceilings exist only for request/response bytes (64 MiB each), so a bug cannot OOM the host through a giant provider frame; those two axes reject `null` and are charged **per frame** (request payload, provider event), not as a run-lifetime sum — a 2 MiB prompt sent forty times is 2 MiB frames, not an 80 MiB parse. Snapshots still report the cumulative `requestBytes`/`responseBytes` counters for telemetry. Every other axis is host policy (0.5.4): omit a key for the default, set a positive safe integer sized to the workload, or set `null` to disable the axis — overnight sessions raise turns/wall/tokens, and a disabled wall still honors `RunOptions.signal`. Resolution stays narrowing-only: `RunOptions.limits` may lower `AgentConfig.limits`, `null` acts as +Infinity (agent 16 + run `null` → 16), and a raised/disabled `maxTurns` lifts an omitted `maxProviderAttempts` (default 24) to at least `maxTurns` so attempts cannot undercut turns; explicitly set attempts values are lifted only when both are finite. Cumulative token counters are billed usage across the whole run, not the context window (`contextBudget` governs window compaction). For production, prefer an explicit `maxCost`: cost needs a finite non-negative amount plus one currency, and when cost is limited, absent, non-finite, or mixed-currency provider cost fails closed. Vendors that omit usage charge their
+labeled estimate (or zero with `usageEstimation: "off"`) to the token counters and never a
+price, so a configured `maxCost` stays the fail-closed envelope for usage-less vendors.
 
-Prism charges turns before assembly, provider attempts before generation, request bytes per request payload, response bytes per provider event (each frame must fit the byte cap on its own), tool rounds before a batch, tool calls before dispatch, and usage before another turn. A breach stops new work, aborts active work through the run signal, emits exactly one redacted `run_limit_exceeded` event/ledger row, and throws `AgentRunError` with `result.limit` (`limit`, `maximum`, `observed`, optional `currency`). Provider-reported token/cost totals arrive after generation, so that completed provider turn can be the unavoidable overshoot boundary.
+Prism charges turns before assembly, provider attempts before generation, request bytes per request payload, response bytes per provider event (each frame must fit the byte cap on its own), tool rounds before a batch, tool calls before dispatch, and usage before another turn. A breach stops new work, aborts active work through the run signal, emits exactly one redacted `run_limit_exceeded` event/ledger row, and throws `AgentRunError` with `result.limit` (`limit`, `maximum`, `observed`, optional `currency`). Just before the terminal `error`, the run also emits one `budget_exhausted` attribution event — the axis that fired, run counters at exhaustion, the three closest other axes, and hashes of the last ten dispatched tool calls ([Agent events § Run limit events](agent-events.md#run-limit-events)). Provider-reported token/cost totals arrive after generation, so that completed provider turn can be the unavoidable overshoot boundary.
 
 `createRunLimitTracker()` and `resolveRunLimits()` are public for adapters that need the same validation and accounting semantics. Workflow agent nodes forward `RunWorkflowOptions.limits`; supervisor delegation narrows its step/tool/token/timeout budget into core limits; MCP tool calls use a per-call tracker.
 
+## Token estimation (provider reports no usage)
+
+When a provider reports no usage, `estimateMessageTokens(messages, modelFamily)` returns a labeled `TokenEstimate` instead of a silent zero. An estimate is never provider truth: reported usage always wins and is never overwritten. The array form reuses the same message flattening as budget accounting and adds the family's per-message chat-template overhead; the single-message form `estimateMessageTokens(message)` remains the numeric budget heuristic used by `contextBudget`.
+
+```ts
+import { estimateMessageTokens, MODEL_FAMILY_TOKENS, resolveModelFamily } from "@arnilo/prism";
+
+const estimate = estimateMessageTokens(messages, "claude-sonnet-4.5"); // model id, provider id, or family name
+// { tokens: 41_200, confidence: "medium", lowConfidence: false }
+```
+
+`MODEL_FAMILY_TOKENS` holds the chars/token ratio, per-message overhead, and confidence label per family (`anthropic`, `openai`, `google`, `deepseek`, `openrouter-generic`, `mistral`, `unknown`). `resolveModelFamily(modelId)` maps a model id or provider id to a table key; unmatched input resolves to `unknown`, whose row is the most conservative (highest estimated token count) and carries `confidence: "low"` / `lowConfidence: true`. Estimates are heuristics, not tokenizers: prose, fenced code, and CJK content are weighted separately, and every calibrated family is `confidence: "medium"` because Prism ships no real tokenizer. The estimator is pure — no network, no I/O, and no content retention.
+
+### Automatic fallback (`AgentConfig.usageEstimation`)
+
+`usageEstimation` is `"fallback"` (default) or `"off"`. With the default, a provider turn that reports no usage records one labeled estimate at the existing usage seam — no adapter changes:
+
+- the `provider_turn_finished.usage` carries `{ inputTokens, estimated: true, confidence }`, and its `budgets.inputTokens`/`runInputUsed` use that estimate, so the attention axes and run limits from plans 086/087 work on non-reporting models;
+- ledger `appendUsage` rows (`scope: "provider_turn"` and the `run_total` aggregate) and `AgentRunResult.usage` keep `estimated: true` (plus `confidence`) — a billing surface can always tell an estimate from a report;
+- estimates are **never priced**: the cost catalog is not consulted, and estimated usage carries no `cost`/`currency`, so a `maxCost` limit still fails closed instead of blocking on invented numbers;
+- `"off"` leaves absent usage absent — no ledger row, no run total, never a zero.
+
+The estimate covers the turn's own request: messages plus tool declarations and context blocks, using the model id's family table.
+
+### `session.contextMeter()`
+
+One state read for host UIs (Clay's token meter, Synapta's model-router budgets):
+
+```ts
+const meter = session.contextMeter();
+// { inputTokens: 43_000, source: "estimated", inputCap: 200_000, runInputBudget: 500_000, usedRatio: 0.215 }
+```
+
+`inputTokens` is the latest provider turn's input tokens — `source: "reported"` when the provider reported them, `"estimated"` when they are the labeled fallback (or, before any provider turn in the session, an estimate of stored history, so a fresh non-reporting model still shows a working meter). `inputCap` is resolved exactly like `provider_turn_finished.budgets.inputCap` (model window minus output reserve minus `attentionCompiler.reserveTokens`), `runInputBudget` is `RunLimits.maxInputTokens` while a run is active, and `usedRatio` is `inputTokens / inputCap`. Cap/budget/ratio are omitted when the model or run cannot derive them. The meter is never billing and never rewrites reported usage; `compact()` drops the pre-compaction reading so the next read re-estimates.
+
+## Clean stops and stop reasons
+
+A run can end without an error but also without the model finishing its thought: a host `RunOptions.turnPolicy.stop`, a `turnPolicy.maxTurns` cap, or a loop ceiling. `AgentRunResult.stopReason` names that outcome — `"host_policy"` for a host policy stop, `"turn_limit"`, `"token_limit"`, or `"refusal"` for loop ceilings — with `turnPolicy.stop`'s own string in `stopDetail`. A natural end carries neither field, so hosts that only care about "did it stop early?" check truthiness. The same values ride the emitted `agent_finished` event (as `finishReason`/`stopDetail`), the finish `RunRecord`, and the projected [Execution Timeline](execution-timeline.md).
+
+A `host_policy` stop is terminal for the run yet resumable: with `runState: { checkpointPolicy: "every-turn" }` the stopped state keeps its frontier, and `resumeAgentRun(..., { decision: "continue" })` picks the loop up at the boundary. Every other terminal state is final. See [Agent loops § Turn policy](agent-loops.md#turn-policy).
+
+## Provider failure classes
+
+Provider-originated failures carry advisory `ErrorInfo.failureClass` on the failed `AgentRunResult`, terminal `RunRecord`, error events, and any `ToolResult.error` that already carries that `ErrorInfo`. Values are `"quota"`, `"auth"`, `"rate_limited"`, `"transient"`, `"permanent"`, and `"unknown"`. The classifier uses an already-captured HTTP status plus bounded error body: quota-shaped `429` responses (for example `GoUsageLimitError`) are `"quota"`; other `429` values are `"rate_limited"`; `401`/`403` are `"auth"`; `5xx` and known network codes such as `ECONNRESET` are `"transient"`; other `4xx` values are `"permanent"`; anything else is `"unknown"`.
+
+This field is outcome metadata, not a retry control. Existing retry policy, attempt limits, and fail-closed behavior continue to use `ErrorInfo.code` exactly as before. Prism records no provider headers or response bodies beyond the existing redacted error message.
+
 ## Durable run state
 
 `RunOptions.runState` writes a bounded, versioned checkpoint only at a safe interruption boundary. Its counters and absolute deadline resume with the run, while transcript history stays in `SessionStore` by session/leaf reference. `AgentRunResult.runState` exposes only redacted identity/status/version data; `interruption` excludes tool arguments. See [Agent/session runtime](agent-session-runtime.md#durable-interruption).
@@ -86,6 +135,8 @@ The adapter receives these record shapes:
 | `status` | `queued` \| `running` \| `suspended` \| `denied` \| `succeeded` \| `failed` \| `aborted`. |
 | `startedAt` / `finishedAt` | ISO timestamps. |
 | `abortReason` | Set when status is `aborted`. |
+| `stopReason` | Why the loop stopped cleanly instead of reaching a natural end: `host_policy` (`RunOptions.turnPolicy.stop`), `turn_limit`, `token_limit`, or `refusal`. Absent on a natural end. |
+| `stopDetail` | Host stop detail from `turnPolicy.stop` (≤256 bytes, redacted). |
 | `error` | `ErrorInfo` when status is `failed`. |
 | `tenantId` / `accountId` / `userId` | From active ownership scope. |
 
@@ -122,7 +173,7 @@ The adapter receives these record shapes:
 | `runId` / `sessionId` / `entryId` | Correlation ids. |
 | `scope` | `provider_turn` for billable source rows; `run_total` for the aggregate. Never sum both scopes. |
 | `turn` / `attempt` | Provider-turn attribution; absent on `run_total`. |
-| `usage` | `Usage` shape: input/output/total/cache tokens, cost, currency. |
+| `usage` | `Usage` shape: input/output/total/cache tokens, cost, currency. Cache fields stay absent when provider does not report them; an explicit provider zero remains `0`. |
 | `recordedAt` | ISO timestamp. |
 
 ## Cost/catalog freshness (host adapter)
@@ -258,7 +309,7 @@ const ledger: RunLedger = {
 
 const agent = createAgent({
   model: { provider: "mock", model: "demo" },
-  provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+  provider: createMockProvider([providerTextDelta("Hello"), providerDone({ inputTokens: 1_000, cacheReadTokens: 800 })]),
   runLedger: ledger,
   ownership: { tenantId: "tenant_a", accountId: "account_a" },
   idempotencyKey: "agent-key",
@@ -276,7 +327,7 @@ console.log(runs.at(-1)?.status); // succeeded
 const billable = usageRows.filter((row) => row.scope === "provider_turn");
 const aggregate = usageRows.find((row) => row.scope === "run_total");
 console.log(cacheUsageReport(aggregate?.usage));
-// { cacheReadTokens: 0, cacheWriteTokens: 0, ... } when provider usage is present
+// { cacheReadTokens: 800, hitRate: 0.8 } — cacheWriteTokens stays absent when unreported
 ```
 
 ## Extension and configuration notes
@@ -296,7 +347,7 @@ console.log(cacheUsageReport(aggregate?.usage));
 - Adapters should treat appends as ordered within a `runId`: event and tool-call rows preserve emission order because the runtime serializes event ledger appends through one promise chain (concurrency 1), drains pending appends before writing the final `RunRecord`, and propagates append failures by rejecting run completion.
 - Billing queries must filter `scope = "provider_turn"`; presentation queries normally read the single `run_total`. `UsageQuery.scope`, `turn`, and `attempt` are explicit filters.
 - Adapters that need upsert semantics can use `RunRecord.id` (== `runId`) as the stable key.
-- Use `cacheUsageReport(record.usage, model)` for cache diagnostics from normalized usage. It works when a provider reports `cacheReadTokens` without `cacheWriteTokens`; missing write tokens are reported as `0`, and unavailable hit rate/savings stay `undefined`.
+- Use `cacheUsageReport(record.usage, model)` for cache diagnostics from normalized usage. It reports `cacheReadTokens` without `cacheWriteTokens` when that is all a provider supplies; neither token field nor hit rate is fabricated as zero. `provider_turn_finished.metadata.cache` carries that same per-attempt report, while `ExecutionTimeline.cacheHitRate` is the input-token-weighted run aggregate.
 - **Provider-specific telemetry is package-owned.** Core `Usage` carries token counts and `cost`/`currency`; it has no energy or detailed cost-breakdown fields. Providers that surface extra telemetry (e.g. `@arnilo/prism-providers/neuralwatt` exposes `neuralWattEventsWithTelemetry()`, `parseNeuralWattComment()`, and `mapNeuralWattTelemetry()` for `: energy`/`: cost` SSE comments and non-streaming top-level fields) keep that data in package-specific helpers/types. Telemetry never enters `RunLedger` usage rows unless the host explicitly copies it in; it carries usage/cost numbers only — never prompts, API keys, or headers. Account-level quota is likewise package-owned: `@arnilo/prism-providers/neuralwatt` exports an explicit `getNeuralWattQuota()` helper that the host calls on demand (never during generation); NeuralWatt rate-limits that endpoint to 1 request per second per customer, so the caller owns throttling.
 - **Governed provider lifecycle and reservation reconciliation.** For invocation-level accounting outside of or in addition to `RunLedger`, wrap providers with `createGovernedProvider` or `router.createGovernedProvider` from `@arnilo/prism-core/governance/model-router`. The adapter handles atomic admission reservations, bounds streaming, and guarantees explicit settlement: missing actual usage on an interrupted or EOF stream is committed as reserved liability (`unknownUsage: true`) rather than zero, avoiding budget leakages or unmetered oversubscriptions. See [Model routing](model-routing.md).
 - **Aggregate task/tenant accounting across all paid work.** Complex agent tasks often span retries, model fallbacks, delegated children, background compactions, embedding jobs, and paid tools. Passing `taskId` and `kind` (`"generation" | "embedding" | "compaction" | "tool"`) coordinates all related calls under a single atomic task-level reservation and budget scope. Committed usage decomposes into separate `byModel` and `byKind` attributions (`router.readBudget({ identity, taskId })`) while preventing double-charging across parent/child boundaries or replayed events. Long-running holds can be safely renewed via `router.renewBudget({ ... })` before expiry without prematurely releasing live liability. See [Model routing](model-routing.md) and [Enterprise PostgreSQL state](enterprise-postgres-state.md).

package/docs/scoped-agent-memory.md

@@ -0,0 +1,262 @@
+# Scoped persistent agent memory — design concept
+
+Status: **concept/proposal**. This page describes a system design for workspace-scoped persistent agent memory — durable facts and procedures that are recorded, updated, and used automatically during agentic work. Nothing here is implemented as a package yet; it is the reference description for the approach. Terminology deliberately aligns with the existing Prism memory surfaces ([memory fabric](memory-fabric.md), [observational memory](compaction-observational-memory.md), [working and semantic memory](working-and-semantic-memory.md)) — see [Relationship to existing Prism memory surfaces](#relationship-to-existing-prism-memory-surfaces).
+
+## Problem and goals
+
+A host running agents over a workspace — a codebase, a professional practice, a research corpus — wants the agent to accumulate durable knowledge across sessions without manual curation: conventions, environment quirks, proven procedures, corrections, user preferences. The system must:
+
+- **Persist** durable facts and procedures per *scope of work* (workspace, codebase, content collection).
+- **Record automatically** — post-task reflection, not user-issued "remember this" commands only.
+- **Stay accurate at scale** — hundreds of accumulated records must not degrade routing, cost, or behavior.
+- **Be auditable** — professional work requires provenance, review, and human override.
+
+The canonical live experiment is the Hermes agent; its documented failure modes at scale define the requirements here.
+
+## Case study: Hermes agent
+
+Hermes (NousResearch/hermes-agent) is a self-improving personal agent. Its memory architecture:
+
+| Layer | Mechanism | Design constraint |
+| --- | --- | --- |
+| Declarative memory | `MEMORY.md` (2,200 chars) + `USER.md` (1,375 chars), injected as a frozen snapshot at session start | Hard capacity: an overflowing write returns an **error that forces consolidation** — never silent growth |
+| Episodic | SQLite FTS5 session search (`session_search`), ~20 ms, no LLM calls | Unlimited, never injected into prompts |
+| Procedural | Skills: markdown `SKILL.md` under `~/.hermes/skills/` (agentskills.io format) | Name + one-line description in the system prompt; full body loaded on demand (`skill_view`) — progressive disclosure |
+| Write loop | Background review agent after each turn, prompt biased toward action: *"most sessions produce at least one skill update"*; bar ≈ 5 tool calls / error recovery / user correction | Patch > edit > create; optional `write_approval` staging gate |
+
+What Hermes got right: bounded always-on memory with capacity-forced consolidation, episodic search off the prompt, progressive disclosure for skill bodies, and a background reflection loop instead of user-driven memory commands.
+
+### Documented failure modes at scale
+
+- **Catalog inflation (issue [#22620](https://github.com/NousResearch/hermes-agent/issues/22620)):** every skill's name + category + description is injected into the system prompt on *every turn*. 243 skills ≈ 10–15K tokens per API call; a 130-skill setup ≈ 4K tokens/turn. Routing is done by making the model attend over the whole catalog, so prompt cost and selection confusion scale O(N) with library size.
+- **Lazy-loading demand (issue [#2045](https://github.com/NousResearch/hermes-agent/issues/2045)):** 87 bundled skills ≈ 1.5–2K tokens before any user content; users manually prune (73 → 26 in one report).
+- **No metabolism (issue [#12877](https://github.com/NousResearch/hermes-agent/issues/12877)):** skills are add-only. No decay, no invalidation, no usage-based cleanup. The library grows monotonically and useful skills are buried under throwaways.
+- **No write-quality gate (#12877 §1):** ~5 tool calls is enough to mint a permanent "skill." A one-off debugging session becomes procedural knowledge with no consolidation or validation — working memory promoted directly to long-term memory.
+- **Skill islands (#12877 §3):** no composition between skills; the same logic (e.g. a TDD workflow) is duplicated across many skills; association fields are decorative.
+- **No conflict detection (#12877 §4):** only identical *names* are blocked; near-duplicate *functionality* competes for execution and produces chaotic output.
+- **Community-validated fix inside #22620:** usage-decay scoring (`score = uses × exp(−Δdays/30)`) plus a hard character budget for the skill list cut catalog tokens ~70% at zero LLM cost — evidence that decay-weighted routing is the right primitive.
+
+**Root cause synthesis:** Hermes solved read-path token economics (progressive disclosure) but left the *routing surface* O(N) in the prompt and gave the *write path* no quality gate, no garbage collection, no deduplication, and no conflict resolution. "Misfiring" is the routing problem: as semantic overlap across hundreds of descriptions grows, selection degrades, and stale or duplicate entries win over correct ones.
+
+## Research basis
+
+| System | Contribution taken |
+| --- | --- |
+| **Mem0** ([arXiv 2504.19413](https://doi.org/10.48550/arxiv.2504.19413)) | Write path as extraction + adjudication: an LLM decides ADD / UPDATE / DELETE / NOOP against existing memories. Solves add-only bloat; strong LoCoMo results against MemGPT/A-MEM baselines. |
+| **Zep / Graphiti** ([arXiv 2501.13956](https://arxiv.org/html/2501.13956)) | Temporal validity as a first-class citizen: every fact carries `valid_at`/`invalid_at`; a new fact *closes* the old one rather than duplicating it. Solves fact staleness and contradiction. |
+| **A-MEM** ([arXiv 2502.12110](https://arxiv.org/abs/2502.12110), NeurIPS'25) | Zettelkasten-style memory: notes carry structured attributes (keywords, tags, contextual descriptions), **link generation** to related notes, and **memory evolution** — new notes update the representations of old ones. Solves island isolation. |
+| **Agent Workflow Memory** ([arXiv 2409.07429](https://arxiv.org/abs/2409.07429), ICML'25) | Procedural induction by mining *repeated* sub-routines across trajectories and abstracting out instance-specific context before storage. Fixes "one successful session becomes a skill." |
+| **Generative Agents** ([arXiv 2304.03442](https://arxiv.org/abs/2304.03442)) | Memory-stream retrieval scored by **relevance × recency × importance**, plus periodic **reflection** that synthesizes higher-level insights once accumulated importance crosses a threshold. |
+| **Voyager** ([arXiv 2305.16291](https://arxiv.org/html/2305.16291v2)) | Skill-library precedent: skills retrieved by embedding top-k, and a skill enters the library only after **execution verification** — promotion gates are not new. |
+| **HippoRAG** ([NeurIPS'24](https://proceedings.neurips.cc/paper_files/paper/2024/file/6ddc001d07ca4f319af96a3024f6dbd1-Paper-Conference.pdf)) | Associative multi-hop recall via knowledge graph + personalized PageRank, for "everything connected to this" queries beyond nearest-neighbor retrieval. |
+| **Letta sleep-time compute** ([arXiv 2504.13171](https://arxiv.org/abs/2504.13171)) | Memory consolidation moved off the interaction path: a background pass reorganizes memory between sessions, improving accuracy while cutting per-turn cost. |
+| **Anthropic Agent Skills** ([engineering post](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)) | Progressive disclosure as a three-level spec; the always-loaded layer (name + description) is the routing surface and must stay tiny. |
+
+## Design principles
+
+1. **Memory is a first-class artifact of the workspace.** Versioned with the workspace, reviewable like code, and *scoped*: a record created in scope X is invisible outside X. One silo per workspace; a separate tiny global layer for user preferences (profile ≠ project).
+2. **Typed memory, one store per type, different physics per type.** Facts are bounded and always-on; episodes are append-only and searchable; notes/insights are linked and evolving; procedures earn permanence through reuse.
+3. **Write-heavy is the failure mode.** Writes are gated by repetition, adjudication, and conflict detection. The default write action is *no-op*.
+4. **Reads are query-driven, never catalog-driven.** Routing happens through a retrieval tool, not attention over an injected list. Prompt cost is O(1) in library size.
+5. **Metabolism, not accumulation.** Usage-decay garbage collection, validity windows, capacity-forced consolidation. Every record can die.
+6. **Abstention beats misfiring.** Below a relevance floor, the memory returns "nothing relevant." An agent confidently following a *wrong* retrieved record is worse than one starting fresh.
+
+## System description
+
+### Scope model
+
+The unit of memory is the **scope**: a workspace root, codebase, project directory, or content collection. Records carry a `scope` binding and are retrieved only within it — scope itself is the largest single precision filter (a query inside `~/work/api-server` never competes with records from other projects). A distinct, optional global scope holds user-profile facts; nothing crosses scope boundaries by default.
+
+### Storage — typed records, not one bucket
+
+```
+<workspace>/.memory/
+  facts.md              # always-on, hard character budget
+  records/*.md          # searchable semantic memory: notes, procedures, insights
+  episodes.db           # SQLite FTS5, append-only session logs
+  index.db              # FTS5 (+ optional embeddings) over records — derived, rebuildable
+```
+
+Record format — markdown with frontmatter, human-editable, git-diffable, PR-reviewable:
+
+```markdown
+---
+id: rec_7f3a91c2d0b4
+type: procedure        # fact | note | procedure | insight
+scope: ~/work/api-server
+status: candidate      # candidate → verified → archived (promotion ladder)
+created: 2026-06-14
+valid: [2026-06-14, ]  # validity window; a superseding write closes it
+provenance: session 8a2f, turn 41   # every claim traceable to its source
+uses: 0                # retrieval activations
+last_used: null
+links: [rec_deploy_rollback, rec_pg_pool]
+---
+## Deploy without downtime
+1. ... (steps abstracted from instance specifics)
+```
+
+Rationale: human override and review are non-negotiable for professional work — diffs, blame, and PR review come free. This mirrors the Hermes `journey edit/delete` lesson (users *must* be able to prune) and generalizes it to full version control.
+
+**Prism realization.** In the composed Prism stack (next section) the [memory fabric](memory-fabric.md) is the source of truth for records and the session store/observational ledger owns episodes; `<workspace>/.memory/` becomes a **git audit mirror** — a rendered export of fabric notes for diff/review — not a second storage engine. One write path, two views.
+
+### Write path — reflect, adjudicate, gate
+
+A background reflection pass runs post-task on the session digest (Hermes's background review; Letta's sleep-time compute), on a cheaper model. Four hard differences from Hermes:
+
+1. **Conservative bias.** The review prompt's prior is *"most sessions update nothing"* — the explicit inversion of Hermes's action-biased prompt. Write triggers: user correction, error→recovery, a technique reused *within* the session, or an explicit "remember this."
+2. **Adjudication before write** (Mem0). Retrieve the top-k nearest existing records; the writer decides ADD / UPDATE / MERGE / NOOP against them. Duplication is killed at write time, not by later cleanup.
+3. **Temporal supersession** (Zep/Graphiti). A contradicting fact closes the old record's validity window — never two live records claiming opposite things. Conflict is detected *at write*, not at misfire time.
+4. **Promotion ladder** (Voyager; #12877 recommendation). Post-task output is a `candidate` note, never a procedure. A candidate becomes `verified` after **N successful reuses** (N ≈ 2–3) logged from actual retrieval→outcome feedback; insights promoted from reflections follow the same gate. Real-but-unproven knowledge lives as a note; only proven repetition earns procedure status. This single gate eliminates most of Hermes's throwaway-skill flood, because throwaways are never reused.
+
+After the gate: **link generation** against retrieved neighbors (A-MEM) so records compose instead of islanding, and every record carries provenance back to the session/turn that produced it.
+
+### Read path — where misfiring is prevented
+
+- **In the system prompt:** `facts.md` only (bounded, ~1–2K tokens) plus one line — "memory available, N records in this scope." Never the record list. Routing is a tool call, not attention over a catalog: prompt cost stays flat regardless of library size.
+- **`memory_search(query)`** — hybrid retrieval: lexical (FTS5/BM25, milliseconds, $0) plus embeddings when available, reranked by a Generative-Agents-style score extended with usage feedback:
+  `score = relevance × exp(−Δdays/τ) × importance × (1 + log uses)`
+  The decay term is exactly the mechanism community-measured at ~70% catalog reduction inside Hermes issue #22620.
+- **Activation budget:** top-3 results per query, and an **abstain floor** — below a similarity threshold the tool returns "no relevant memory."
+- **Link traversal:** follow `links:` one hop for associative recall (HippoRAG-lite). No graph database — frontmatter adjacency only.
+
+### Lifecycle — metabolism
+
+An idle/nightly consolidation pass (cheap model, off the interaction path):
+
+- **Garbage collection by usage decay.** Archive `candidate` records unused for ~30 days; archive `verified` records below a usage-decay threshold. Recommend-then-delete, never silent deletion (git keeps history regardless).
+- **Near-duplicate merge.** Records flagged by embedding similarity above threshold are merged or invalidated.
+- **Promotion/demotion** per the ladder, from logged retrieval→outcome feedback.
+- **Capacity-forced consolidation of `facts.md`.** When a facts write would exceed the budget, the write *fails* with "consolidate first" (the Hermes overflow-error pattern) — the writer must merge or remove entries in the same action. The always-on layer can therefore never rot.
+- **Digest.** A weekly human-readable diff of memory changes (git already provides the bookkeeping).
+
+### Trust boundary
+
+- **Injection/exfiltration scanning** of record content before any prompt injection (patterns, invisible Unicode) — Hermes does this for `MEMORY.md`; extend to all records.
+- **Staged approval.** Writes may be staged for human review (`write_approval`-style). Default: off for personal scopes, on for team/professional scopes.
+- **Scope isolation.** Records never leak across workspace roots; the global user layer is opt-in per record.
+- **Provenance on every record.** Any memory-driven decision can be traced to the session and turn that produced the record (same philosophy as observational memory's source-backed ids and the recall path).
+
+## Failure-mode → mechanism map
+
+| Hermes failure mode | Mechanism here | Backing |
+| --- | --- | --- |
+| Catalog tokens O(N)/turn | Routing via retrieval tool; never list injection | #22620, #2045; Anthropic three-level disclosure |
+| Wrong entry wins selection | Abstain floor + top-3 budget + decay-weighted scoring | Generative Agents; measured decay fix in #22620 |
+| Throwaway-skill flood | candidate→verified promotion after N reuses | Voyager verification; #12877 §1; AWM repetition mining |
+| Duplicates | Write-time ADD/UPDATE/MERGE/NOOP adjudication | Mem0 |
+| Contradictory live facts | Validity windows; supersede, don't duplicate | Zep/Graphiti |
+| Record islands | Link generation + memory evolution on write | A-MEM; HippoRAG traversal |
+| Unreviewable autonomous writes | Markdown + git + provenance + staged approval | Hermes `journey`/`write_approval` generalized |
+| No cleanup | Usage-decay GC + consolidation pass | Letta sleep-time; #12877 §2 |
+
+## Evaluation
+
+Non-negotiable for professional use; memory must earn its complexity:
+
+1. **Task win-rate A/B** — a fixed task suite per scope, run with memory on / off / never-consolidated. If memory does not lift win rate or reduce turns, it ships off by default.
+2. **Retrieval precision@3** against a hand-labeled query set per workspace; alert on drops — the leading indicator of misfiring.
+3. **Health metrics** — duplication rate, candidate→verified conversion rate, activation rate (retrieved-and-used / retrieved), and prompt token cost per turn vs. library size (target: flat).
+4. **LoCoMo-style recall probes** for the episodic layer, the standard benchmark in the Mem0/Zep line.
+
+## Relationship to existing Prism memory surfaces
+
+The placement principle: **the scoped layer is a policy and lifecycle layer, not a fifth store.** Mechanism lives in the engines and the fabric; policy lives in the scoped layer. This section concretizes how the layers compose into one memory-management system.
+
+### Layered architecture and ownership
+
+| Layer | Surface | Owns | Never does |
+| --- | --- | --- | --- |
+| Raw transcript | [Session stores](session-stores.md) | append-only entries, branches, bounded lexical search | — |
+| Episodic ledger | [Observational memory](compaction-observational-memory.md) | source-backed observations/reflections (12-hex ids, `sourceEntryIds`), exact-id recall and branch pages, optional work-scope index; observer/reflector/dropper workers are the only writers | no semantic retrieval, no wholesale prompt injection, no downstream re-observation |
+| Memory engines | [Working and semantic memory](working-and-semantic-memory.md) | `Embedder`/vector/working-store contracts, consent lifecycle, lineage invalidation, importance, recall scoring | no policy |
+| Durable records | [Memory fabric](memory-fabric.md) | typed notes (`fact`/`procedure`/`file`/`working`/`episode`), validity windows, consolidation folding, linker/evolution workers, five governed tools, file jail, context provider, `forget`/legal hold | no autonomy — every write is an explicit caller decision |
+| Policy + lifecycle | **Scoped memory (this concept)** | conservative post-run writer, promotion ladder, usage-decay GC, abstain floor + activation budget, workspace-root scope identity, git audit mirror | no store, no engine, no context-block type, no second write path |
+
+Two invariants carry over unchanged: observational memory stays **episodic** (promotion out of the ledger is an explicit host write — fabric's `promotedFrom` over a closed work scope), and the fabric never widens consent or visibility.
+
+### Ideal composition for a persistent-memory agent
+
+```ts
+// 1. Engines — workspace root becomes the silo identity
+const memory = createMemory({ tenantId: host, resourceId: workspaceRoot, embedder, stores });
+// 2. Durable records — folding, links, evolution on by policy
+const fabric = createMemoryFabric({ memory, observational, consolidate: { threshold: 0.85 },
+                                    linker: { enabled: true }, evolution: { enabled: true } });
+// 3. Episodic ledger per session; work-scope index bound to the workspace
+om.attach(session);
+// 4. Gate fabric tools + workers to this session
+fabric.attach(session);
+// 5. Injection: ONLY the bounded working facts block reaches the prompt
+registries.contextProviders.register("memory-fabric", fabric.createContextProvider());
+const agent = await resolveAgentDefinition(
+  { name: "assistant", model, context: ["memory-fabric"], tools: ["memory.recall"] },
+  { registries, providerSource });
+// 6. Scoped policy module (host-side, the new part): post-run review,
+//    usage logging on recall hits, idle promotion/GC jobs, .memory/ git mirror
+```
+
+End-to-end flow:
+
+1. **During the session** — observational workers record source-backed observations/reflections; compaction renders prepared memory; the agent may call `memory.recall`/`memory.insert` directly; the prompt carries only the bounded facts block.
+2. **After the run** — the scoped policy reviews the session digest on a cheap model, biased to no-op, and promotes the *generalizable* part through `fabric.remember` as `candidate` notes carrying `sourceEntryIds` provenance (or `reflectionId` for notes derived from a closed-scope reflection). Folding adjudicates duplicates; linker/evolution connect and refine.
+3. **Next session** — facts block (working notes) always on; everything else via `memory.recall` (`kinds: ["procedure"]` stays opt-in, `asOf` honors validity, `budget` caps tokens). Recall hits log `uses`.
+4. **Idle/nightly** — promotion job converts candidates with N logged successful reuses to `verified`; usage-decay GC archives the rest; the facts block is consolidated under its budget; the git mirror renders the diff for human review.
+
+### Read/write paths across layers
+
+| Write-path step | Owner |
+| --- | --- |
+| Trigger (post-run, noop-biased) | scoped policy |
+| Extraction with provenance | observational reflection → `reflectionId`/`sourceEntryIds` |
+| Adjudicate ADD/UPDATE/supersede | fabric consolidation folding (cosine threshold 0.85) |
+| Close contradicted facts | fabric `validTo` + `supersedes` |
+| Link + evolve neighbors | fabric linker/evolution workers |
+| Status `candidate`, staging/approval | scoped policy |
+
+| Read-path step | Owner |
+| --- | --- |
+| Always-on bounded facts | working block via the fabric context provider — the only injected surface |
+| Query-driven records | `memory.recall` (kinds/asOf/budget) + scoped abstain floor, top-3 budget, decay-weighted scoring |
+| Associative recall | `links` traversal (recall hits with `explain.link: true`) |
+| Episodic specifics | observational exact-id recall / `searchConversation` lexical pages |
+
+### Research leverage map
+
+How the research findings land on shipped surfaces versus policy added by this concept:
+
+| Finding | Source | Shipped in Prism | Added by this concept |
+| --- | --- | --- | --- |
+| Write adjudication (ADD/UPDATE/DELETE/NOOP) | Mem0 | fabric consolidation folding (insert / rewrite / supersede) | MERGE of near-duplicates in the GC pass |
+| Importance weighting | Mem0 | `importance` / `importanceFrom` hook | — |
+| Temporal validity windows | Zep/Graphiti | fabric `validFrom`/`validTo`, recall `asOf` | — |
+| Invalidate, don't duplicate | Zep/Graphiti | supersede fold at write | — |
+| Bi-temporal time (event vs ingestion) | Zep/Graphiti | `tRef` vs `ingestedAt` | — |
+| Link generation | A-MEM | fabric linker worker | — |
+| Memory evolution | A-MEM | fabric evolution worker | — |
+| Relevance × recency × importance scoring | Generative Agents | fabric recall scoring (similarity/recency/importance) | usage feedback `(1 + log uses)` + exp decay |
+| Verify before permanence | Voyager | — | promotion ladder (N reuses) |
+| Mine repeated routines, abstract instance specifics | AWM | — | conservative review writes abstracted candidates |
+| Off-path consolidation | Letta sleep-time | — (idle-job placement) | GC/promotion/facts consolidation on a cheap model |
+| Tiny always-loaded layer, disclosure on demand | Anthropic skills | recall tools + working block only | abstain floor + top-3 activation budget |
+| Hybrid BM25 + cosine + graph walk | Zep/Graphiti | partial: embedding score + link traversal; lexical on branch search | fusing lexical into one recall — open question |
+
+### Deliberate deviations
+
+- **Against Mem0's accumulate-and-rank-at-query.** Mem0's current algorithm appends dated variants and ranks at query time. This design sides with Zep: close the validity window at write. Rationale: the scoped layer injects few records, so each must be *the* trusted record; ranking dated variants at retrieval reintroduces the Hermes catalog/misfire problem one layer down.
+- **Beyond both Mem0 and Zep.** Neither gates *procedures* by reuse — that is exactly the Hermes failure (#12877: ~5 tool calls = permanent skill). The promotion ladder is the addition, from Voyager/AWM.
+- **Not adopted (deferred):** graph engines and community detection (frontmatter `links` + one-hop traversal suffice inside a scoped silo); Zep-style episodic subgraph summarization (the observational reflector already does hierarchical episodic summarization with provenance — adopting it would duplicate a shipped layer).
+
+## Non-goals / deferred
+
+- No vector database, graph database, or external memory provider in the core design — embeddings only where lexical retrieval measurably fails (inside a scoped silo it mostly will not).
+- No second write path — the scoped policy writes only through the fabric, so folding, consent, and lineage rules apply to every write.
+- No cross-scope federation or sharing; add only when a multi-workspace pattern measurably needs it.
+- No autonomous deletion of human-authored records; GC proposes, humans dispose.
+
+## Open questions
+
+- Exact promotion thresholds (N reuses, decay τ, similarity floors) — must be empirically tuned per workload class (coding vs. research vs. professional ops).
+- Whether the global user-profile layer reuses the working-memory store or a separate facts silo.
+- Evaluation harness: reuse the existing evaluations/trajectory tooling vs. a purpose-built memory replay suite.
+- Team-scope semantics: per-user silos sharing one workspace root, or one shared silo with author-attributed records.

package/docs/server.md

@@ -264,6 +264,8 @@ A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-core/
 - [MCP client and server exposure](mcp-tools.md): selected MCP capabilities and web-standard MCP transport.
 - [Host security guide](host-security.md): remote-boundary checklist.
 - [A2A interoperability](a2a.md): separately mounted A2A 1.0 handler/client.
+- [Telegram channel](telegram-channel.md): separately mounted Telegram Web `Request`/`Response` webhook handler; host owns fixed HTTPS route and TLS.
+- [Signal channel (experimental)](signal-channel.md): private Unix-socket manual receive for an externally supervised signal-cli daemon; host owns socket, account, accepted-use policy and supervision.
 - [Obscura browser engine](obscura.md): optional binary-backed generic tools for hosted agents.
 - [Conversations](conversations.md): durable user-scoped conversation service, replay, branches, export, deletion.
 - [Work artifacts and review](work-artifacts-and-review.md): durable artifact review service, revisions, approvals, authorized expiring delivery links.

package/docs/session-store-conformance.md

@@ -25,8 +25,7 @@ Use this helper when implementing a DB-backed `SessionStore` (for example, the r
 - session ids remain isolated (`assertSessionStoreConforms` always probes a secondary session)
 - optional concurrent fork children of the same parent succeed when `exerciseConcurrentParentAppend: true`
 - optional durable reopen/idempotency survival when `runSessionStoreConformance(..., { exerciseReopen: true })`
-- optional `searchSessions` bounds/ownership/empty-page checks when `exerciseSearchSessions: true` (`assertSessionStoreSearchSessions`)
-- optional `searchSessions` bounds/ownership/empty-page checks when `exerciseSearchSessions: true` (`assertSessionStoreSearchSessions`)
+- optional `searchSessions` case when `exerciseSearchSessions: true` (`assertSessionStoreSearchSessions`): invalid limit/query/kind rejection, empty-page bounds, limit cap, a written-message round-trip asserting `entryId`/`runId`/`turn`/`snippet` point at the match, one hit per session when a second entry also matches, the `kind` filter excluding non-matching entries, and ownership bounds
 
 ## Inputs / request
 

package/docs/session-stores.md

@@ -24,7 +24,7 @@ import type { SessionStore, SessionEntry } from "@arnilo/prism";
 | `list(sessionId)` | Return all entries for one session in stored order. Development fallback for branch reads. |
 | `get?(id)` | Return one entry by id, if present. Optional. |
 | `readBranchPath?(query)` | Optional DB-friendly branch read. Return one branch's ancestor chain as a `PersistencePage<SessionEntry>` so the runtime can avoid `list(sessionId)`. |
-| `searchSessions?(query)` | Optional bounded session search (`SessionSearchQuery` → `PersistencePage<SessionSearchHit>`). SQLite/Postgres implement FTS + metadata filters; memory default is linear; JSONL throws `SessionSearchUnsupportedError`. |
+| `searchSessions?(query)` | Optional bounded session search (`SessionSearchQuery` → `PersistencePage<SessionSearchHit>`). SQLite/Postgres implement FTS + metadata filters; memory and JSONL scan linearly (JSONL re-reads its file per query). |
 
 Public helpers:
 
@@ -110,9 +110,13 @@ Recognize it with `isSessionAppendConflict(error)`, not message text. Built-in s
 - Branch semantics are parent links plus a leaf id. External UIs should keep branch handles as `(sessionId, leafId)`; RPC exposes an additional `handleId` for active handles.
 - Development stores can omit `readBranchPath`; the runtime falls back to `list(sessionId)` and the pure in-memory branch walk. Database-backed stores should implement `readBranchPath` so `entries()`, `clone()`, and context rebuild read only the selected ancestor chain.
 
-## Session search (0.0.11)
+## Session search
 
-Bounded `SessionIndex` / `searchSessions` lists sessions by optional `workspaceRoot` (`metadata.workspaceRoot`), provider/model, label/summary, time range, ownership, and optional text `query` (FTS on SQLite/Postgres; case-sensitive substring on memory linear). Hits require `sessionId` and may include `leafId` for `checkout`; never credentials or whole transcripts.
+Bounded `SessionIndex` / `searchSessions` lists sessions by optional `workspaceRoot` (`metadata.workspaceRoot`), provider/model, label/summary, time range, ownership, and optional text `query`. SQLite/Postgres run indexed full-text search; the memory and JSONL stores scan linearly (case-sensitive substring, capped by the contract linear caps; JSONL re-reads and parses its file per query, see [Node JSONL session store](node-jsonl-session-store.md)). Hits require `sessionId` and may include `leafId` for `checkout`; never credentials or whole transcripts.
+
+When a text `query` matches, the hit points at one matched entry per session (the store's best-ranked match on the indexed SQLite/Postgres paths, the first match in transcript order on the linear memory/JSONL paths): `entryId`, `runId`, and a 1-based `turn` (transcript position, `(timestamp, id)` order) locate it, `score` is the store relevance where the store has an index (higher is better; SQLite bm25 negated, Postgres `ts_rank_cd`; absent on linear stores; a non-discriminative term can legitimately score 0, so test for presence, not `> 0`), and `snippet` is bounded context around the match in that entry. Hits stay ordered by session `updatedAt` with cursor pagination, so hosts rank by `score` client-side when they want relevance order.
+
+`SessionSearchQuery.kind` restricts which entry kinds the query may match (one kind or a list; omitted or `"any"` = all). Annotation search is `kind: ["label", "summary", "metadata", "custom"]`; `kind: "label"` without a `query` lists sessions that carry an annotation entry. Unknown kinds fail closed with `TypeError`. Indexed text is transcript message text plus label/summary - tool arguments and tool results are never indexed, so they cannot leak through search.
 
 ```ts
 import { createMemorySessionStore, resolveSessionSearchQuery } from "@arnilo/prism";
@@ -121,32 +125,28 @@ const store = createMemorySessionStore([], { sessionSearchMode: "linear" });
 const page = await store.searchSessions!({
   workspaceRoot: "/repo",
   query: "flake",
+  kind: "any",
   limit: 20,
 });
+// [{ sessionId, leafId, entryId, runId, turn, score, snippet, ... }]  // score is absent on linear stores
 // Opt out: createMemorySessionStore([], { sessionSearchMode: "unsupported" })
 // Raise the in-process scan caps for a small but large-query session set (defaults are the contract caps):
 const wide = createMemorySessionStore([], { search: { maxLinearSessions: 5_000, maxLinearEntries: 50_000 } });
 ```
 
-Finite caps (defaults / hard): page 20/100; query string 4 KiB/16 KiB; snippet 512 B/4 KiB; cursor 1 KiB/4 KiB; memory linear sessions 1000/5000, entries 10000/50000, bytes 8 MiB/64 MiB; DB FTS candidates 1000/5000. Overflow fails closed via `resolveSessionSearchQuery`. See [Phase 6 evidence](_evidence/review-coverage-2026-07-22-phase-6.md).
-
-## Session search (0.0.11)
-
-Bounded `SessionIndex` / `searchSessions` lists sessions by optional `workspaceRoot` (`metadata.workspaceRoot`), provider/model, label/summary, time range, ownership, and optional text `query` (FTS on SQLite/Postgres; case-sensitive substring on memory linear). Hits require `sessionId` and may include `leafId` for `checkout`; never credentials or whole transcripts.
+The JSONL store exposes the same `searchSessions` contract through the same matcher, with no index:
 
 ```ts
-import { createMemorySessionStore, resolveSessionSearchQuery } from "@arnilo/prism";
+import { createJsonlSessionStore } from "@arnilo/prism/node/session-store-jsonl";
 
-const store = createMemorySessionStore([], { sessionSearchMode: "linear" });
-const page = await store.searchSessions!({
-  workspaceRoot: "/repo",
-  query: "flake",
-  limit: 20,
-});
-// Opt out: createMemorySessionStore([], { sessionSearchMode: "unsupported" })
+const store = createJsonlSessionStore("./sessions.jsonl");
+const page = await store.searchSessions!({ workspaceRoot: "/repo", query: "flake", limit: 20 });
+// Every query reads and parses the file: O(corpus) time and memory, caps default to the linear caps.
 ```
 
-Finite caps (defaults / hard): page 20/100; query string 4 KiB/16 KiB; snippet 512 B/4 KiB; cursor 1 KiB/4 KiB; memory linear sessions 1000/5000, entries 10000/50000, bytes 8 MiB/64 MiB; DB FTS candidates 1000/5000. Overflow fails closed via `resolveSessionSearchQuery`. See [Phase 6 evidence](_evidence/review-coverage-2026-07-22-phase-6.md).
+Finite caps (defaults / hard): page 20/100; query string 4 KiB/16 KiB; snippet 512 B/4 KiB; cursor 1 KiB/4 KiB; memory linear sessions 1000/5000, entries 10000/50000, bytes 8 MiB/64 MiB (also the JSONL scan caps); DB FTS candidates 1000/5000. Overflow fails closed via `resolveSessionSearchQuery`.
+
+Sizing (plan 095): SQLite FTS5 and the Postgres `tsvector` column are maintained additively at append time (no background job). On the 100k-turn fixture in `scripts/benchmark-scenarios/session-search.mjs` (stored tool output, which is never indexed), the index is 18.8% of transcript page bytes and query p95 is 38 ms (`node scripts/benchmark.mjs --scenario session-search`; ceiling 100 ms). Stores receive already-redacted entries, so the index inherits the same redaction as session reads. Unindexed stores (memory, JSONL) trade that cost for O(corpus) per query — see `examples/session-search.ts` for both paths side by side.
 
 ## Security and performance notes