Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
10.5 KB
Raw Blame

Variants - delivery-trust

Audit trail for the phase-0 brainstorm. These variants are generated in-session for this run; the same text lives at cli-output/consultant.md. In host execution mode the consultant is an in-session subagent of the design orchestrator, not the external claude CLI used by earlier cycles; the prompt at cli-output/prompt.md and the verbatim output at cli-output/consultant.md are preserved either way. Each variant is a shape for the whole wave - how the four cards compose into one coherent design - not a per-card design (the per-card approaches come from the four recon reports and are identical across variants).

Variant 1: Central egress gate at the server boundary

  • Approach: Grow the one place response bytes are already reach-shaped - the MCP server's result builder and its error redaction, both of which already branch on transport reach - into a full delivery gate: every structured tool result and resource payload passes a shaper that probes each row's provenance and fences below-operator-authorship text before the response leaves, the receipt-verify verb and the attestation verification are exposed as read-side services beside it, and the opencode plugin consumes the same gate by spawning the shared hook shims.
  • Trade-offs:
    • Pros: one rule in one place, so no surface can forget shaping; new read surfaces inherit the fence automatically; the gate already exists as the redaction precedent, so the branch point is proven; the wave gets one obvious story - everything a remote reader receives passes one door.
    • Cons: the boundary sees opaque JSON - per-row provenance is not in the payload, so the gate must re-read vault files by reconstructing paths from result shapes, fighting the per-tool output contracts and the two existing view families; structured rows and text/markdown resources need different mechanics through one function; results parked in the artifact store before the caller fetches them would bypass the gate on replay unless the gate re-shapes there too, which it cannot without per-request reach; the per-surface census rows lose their written reasons because the decision no longer lives at the surfaces.
  • Complexity: large
  • Risk: high

Variant 2: Family-seam shaping over shared pure kernels

  • Approach: Build two pure leaf modules - a closed treatment vocabulary with the fail-closed derivation from the existing stamps (origin_channel, content_class, untrusted_source) and a cached frontmatter provenance probe - then wire them per surface family at the seams those families already own: search rows at the snippet-windowing site, report-shaped reads through one binding beside the existing reach-events reference view, whole-document resources at their readers. The verify verb is a pure kernel over the receipts family with two thin faces (an operation on the existing MCP receipts tool, a CLI subcommand); the opencode lane registers an execute.before gate and a prompt-observe hook that spawn the existing shims and drain a per-turn queue through the existing context hook; the attestation kernel binds per-shard heads and state-surface stamps under an operator Ed25519 key, sharing only the digest and seal primitives.
  • Trade-offs:
    • Pros: no second architecture - every wire point is a seam that already decides what a reader may see, so the frozen conventions (fail closed, identical to absent) and the local-reach byte-identity pins hold untouched; the fence lives in the delivered bytes so output schemas stay unchanged; the four lanes own disjoint families and share only pure modules and append-only registries; census registries keep their per-surface meaning.
    • Cons: shaping lives at several call sites, so a future read surface can forget it - mitigated by teaching the visibility-surface census the shaper's name and pinning each family with a remote-quoted/local-identical test; more total wiring code than one central gate; the treatment vocabulary must be registered in the verdict-vocabulary census like any other closed set.
  • Complexity: medium
  • Risk: low

Variant 3: Delivery pipeline framework

  • Approach: Introduce a typed delivery-pipeline object - stages for reach gating, provenance fencing, preview-budget parking and receipt emission - that every read handler constructs its response through; policy changes become stage registrations, the opencode lane implements the same pipeline interface over its hook events, and attestation attaches as a pipeline observer signing the state the pipeline read from.
  • Trade-offs:
    • Pros: future delivery policy becomes configuration rather than surface edits; one type documents the whole delivery contract; receipts and fencing cannot disagree because one object produces both; the pipeline is the natural home for the queue-then-context drain on the opencode lane.
    • Cons: migrating roughly forty read surfaces onto a new abstraction is a wave of its own riding a wave that is supposed to ship four cards; the pipeline type duplicates rules the two existing view families and the search result filters already encode and pin by test, so every existing reach test rewrites or fights it; the artifact-store parking order and the preview budget are load-bearing today and re-deriving them inside pipeline stages risks subtle regressions in the oversized-result path.
  • Complexity: large
  • Risk: high

Recommended: Variant 2

Rationale: The repo already encodes delivery rules as per-family views with frozen conventions and per-tool output contracts, both pinned by tests; Variant 1's central gate cannot see per-row provenance in opaque results and would have to re-read files at the boundary, while Variant 3 rebuilds machinery that exists and would rewrite the reach test corpus for no new capability. Variant 2 adds exactly what is missing - one pure treatment kernel, one cached provenance probe - and wires it where each family already decides what a remote reader may see, which keeps the four lanes disjoint, the local-reach contracts byte-identical, and the census registries meaningful.

Orchestrator decision

Chosen: Variant 2 (the recommended variant; no override).

Premise verification

Spot-checked against the live worktree at 285cb9a8 (branch feat/delivery-trust) on 2026-11-01. No premise was refuted; no slice is dropped. Line drifts are recorded as corrections for the plan; the validator's refreshed anchors all held exactly.

Card Premise Key anchors checked live Result
t_1af24938 confirmed provenance.ts:41/:44/:69 (stated>deduced>inferred, PROVENANCE_LEVELS, provenanceTrustRank); origin-channel.ts:86 (mcp-tool/cli/import), :109 unset, :123 field; trust/untrusted-provenance.ts:31/:50/:77/:90; untrusted-source.ts:33/:176/:188/:219 (wrapUntrustedSource)/:238 (fenceUntrustedContent); safety/context-guard.ts:3; context-pack.ts:799-807 guard site with delimitUntrusted at :804; policy/blocks/guardrails.ts:86 (untrusted_source_delimiting: false); trust/retrieval-gate.ts:66 (untrusted_source_provenance); tool-error-codes.ts:136 (quote_unverified); transport-reach.ts:40/:79/:97; tool-contract.ts:168/:305; reach-refusal.ts:44/:89; error-redaction.ts:54/:61; server.ts:802; search-tools.ts:745 (windowContent); reach-view.ts:40; artifact-ref-view.ts:20-29 (the two conventions verbatim); stdio.ts:42; http.ts:601; no per-page verified flag exists Exact, except VISIBILITY_SURFACE_REGISTRY is at visibility-surface-registry.ts:86 (recon said :81; DIRECT_VAULT_READ_REGISTRY :1459 exact) and CONTENT_CLASS is at content-class.ts:89 (recon said :69; field constant :96 exact). Corrections recorded for the plan.
t_4300e5fd confirmed ContextReceiptFilter.receiptId at context-receipts.ts:101; text_hash / session_id / final_text_hash at :155-163; sourceRefs hash duplication at :178-187; emitContextReceipt:137; listContextReceipts:203; summarizeContextReceiptSession:374; getContextReceipt:474; structural ids :829; CONTEXT_RECEIPT_TRIGGERS:846; emit sites context-pack.ts:1790 and budget :1887, pre-compress-pack.ts:297, hooks/active-inject.ts:592/:599 (session_inject, no text); digest.ts:54/:64/:82/:106/:118; content-hash.ts:32/:71; docs rows docs/cli-reference.md:473/:534, docs/mcp.md:407 Exact, except pre-compress-pack.ts emit is at :297 (recon :295) and recordInjectionSize at active-inject.ts:592 with the trigger at :599 (recon :596). Corrections recorded for the plan.
t_eaf760a6 confirmed Plugin plugins/opencode/open-second-brain.ts (549 lines): capture branch :393-395, experimental.chat.system.transform :404, tool.execute.after :415, default export :460, ctx.session.hook("context") :479, ctx.tool.hook("execute.after") :488, ctx.event.subscribe :506, CAPTURE_EVENTS:49, V2_CAPTURE_EVENTS:50, MUTATING_TOOLS:64, HOOK_TIMEOUT_MS:68, renderActiveContext:281, hookCommand:338; NO tool.execute.before / tool.hook("execute.before") and no prompt hook anywhere in the file; hooks/hooks.json UserPromptSubmit :80 (rows session-capture :86, recall-inject :92, nav-inject :98, counterparty-brief :104, reground-deliver :110), PreToolUse :117 (pretool-orient :123, pretool-host-backup :134); codex mirror runs pretool-orient at plugins/codex/hooks/hooks.json:137; INSTALL_TARGET_ID.opencode at host-facts.ts:70 Exact at the validator-refreshed anchors; the card's own :62/:93 and :297-338 are the stale spellings the validator already corrected. The parity gap is real: no denial hook and no prompt-submit row on the opencode lane.
t_3bdb82b0 confirmed grep -rn "ed25519|createSign|createVerify|generateKeyPair" src/ plugins/ returns zero hits; verifyLogChain at log-chain.ts:156; lastChainHash at log.ts:568 is module-private (no exported head reader exists); LOG_CHAIN_FIELDS:523, logChainHash:546, renderJsonlLine:496, acquireLogLock:289, appendLogEvent:320; trust.ts receipt head fields (actor, pid, before-hash, summary) in the docblock at :18; STATE_SURFACES at state/surfaces.ts:378; DOCTOR_CHECKS at doctor.ts:181; loadOrCreateKey at secrets/crypto.ts:93; restrictToOwner at secrets/owner-acl.ts:116; checkpoint-store.ts:42/:72/:83/:113; docs docs/cli-reference.md:437 (log verify) and :442-444 (snapshot family) Exact. Two load-bearing facts beyond the card: the log head scanner is private (the wave must add an exported, lock-taking head collector in log.ts), and there is no whole-store digest function anywhere.