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.
Knowledge Provenance Suite - variant audit trail
Primary consultant: Claude Code (claude -p), exit 0, three parseable variants.
Fallback (Codex) not invoked - primary returned a clean, complete set.
The full consultant output is preserved verbatim in cli-output/claude.md. The
three variants and the consultant's recommendation are reproduced below, followed
by the orchestrator decision.
Variant 1: Unified staged-intake kernel
- Approach: Generalize the existing
write-sessionkernel into ONE provider-agnostic "intake transaction" that every generation-bearing feature (ingest, research-report, derived-facts, on-write NER) funnels through: the agent proposes a typed payload across an MCP/CLI boundary, OSB validates -> provenance-stamps -> cross-links -> atomically commits. Primitive (a) is the discriminatedExtractionIntakepayload shared by ingest and NER, (b) is aProvenancevalue object stamped at commit, (c) reusesagent-scope.tsfor owner fields. Features 2/3/6 become payload variants or phases of the same commit path. - Trade-offs: Maximum DRY and one tested seam for provenance/atomicity, but
a large upfront abstraction conflicts with one-feature-at-a-time TDD (first
commits carry the most risk), over-generalization invites leaky union types or
ascrutches, and per-feature atomic revertability is hardest. - Complexity: large
- Risk: high
Variant 2: Per-feature pipelines over three shared libraries
- Approach: Each feature is its own module/pipeline with its own MCP tool or
CLI command and its own TDD unit (
ingest.ts,research.ts, aderivephase indream.ts,ner.ts, owner-scoped facts onpreference-txn.ts, an extension toattention-flows.ts), but all import three shared library functions rather than duplicating logic:extractIntake()(primitive a, shared by ingest + NER),stampProvenance()/citation builder (primitive b, shared by ingest + research + derive), and the existing owner-visibility helpers (primitive c). The generation boundary sits at each feature's own tool; each pipeline sequences-validates-commits using the shared libs (mirroringimportSession's dedup-hash blueprint). - Trade-offs: Matches the repo's domain-module decomposition and the one-atomic-commit-per-feature TDD constraint exactly; risk is isolated per feature; DRY is enforced via three named exports without a monolith; flags stay independently opt-in. Cons: larger MCP/CLI surface, repeated sequencing boilerplate, and shared-lib usage is discipline-dependent (drift possible without review vigilance).
- Complexity: medium
- Risk: low
Variant 3: Read-time provenance/visibility resolver with thin write adapters
- Approach: Push provenance, trust-ordering, and owner-scoping entirely into
a read-time derivation at
packContext/recall time, governed by frontmatter tokens and wikilinks; writes stay "dumb". Generation features become thin agent-side adapters that emit notes with the right frontmatter, while oneresolveProvenance()/resolveVisibility()layer at the read chokepoint does all ordering and filtering. - Trade-offs: Strongest byte-identical-when-off guarantee (storage unchanged); trust ordering and owner filtering in one read seam. Cons: ingest and research are inherently write-heavy multi-page operations that do not fit a pure read-time model, so the resolver only covers 3/6 features and a hybrid is unavoidable; recomputing on every assembly adds read-path cost and complicates caching against the O(1) graph side-index; frontmatter-only provenance is brittle under hand edits with no commit-time validation.
- Complexity: medium
- Risk: medium
Consultant recommendation: Variant 2
The consultant recommended Variant 2 as the only variant that fits the hard
process constraints (one feature at a time via TDD, one atomic revertable commit
per unit, single 50-70 file PR), because each pipeline lands independently while
three named shared exports satisfy the DRY mandate without a monolithic kernel.
It mirrors the repo's own precedents (importSession, write-session, the v1.2
domain decomposition) and keeps each opt-in flag and its byte-identical-off
guarantee isolated. Variant 1 front-loads risk against the TDD cadence; Variant 3
cleanly covers only the read-side half of the suite.
Orchestrator decision: accept Variant 2, with one hardening
Accepted. Variant 2 is the correct fit for this repo's TDD/atomic-commit cadence and the single-PR constraint, and it is the only variant under which a flawed ingest pipeline cannot regress derived-facts.
One hardening is added to close Variant 2's single weakness (shared-lib usage is discipline-dependent): the three shared primitives are made the ONLY exported way to perform their operation. There is no public alternative write path for extraction-intake or provenance-stamping - features import the shared export or they do not compile. This converts "drift is possible without review vigilance" into a type-and-module-boundary guarantee, recovering Variant 1's single-seam benefit without its monolith or its front-loaded risk.
A second clarification follows directly from the project's provider-agnostic kernel (OSB never calls an LLM): for the four generation-bearing features (ingest, research, derived-facts, NER), all model generation lives on the agent side of an MCP/CLI boundary. OSB owns only the deterministic half - sequencing, validation, provenance-stamping, idempotent dedup, and the atomic vault write - which is exactly the half that is testable and the half the operator agreed to cover with tests. No ML dependency is bundled anywhere in the suite.