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.
Memory subsystem alignment β design
Problem
Open Second Brain declares itself as a Hermes memory provider, but its memory-write path is not aligned with the live Hermes memory semantics that motivated this release. brain_pinned_context currently accepts oversized content as a successful write while sanitiseTextField silently truncates it, writer tools are single-operation surfaces that cannot consolidate and add in one atomic turn, and the declared on_memory_write hook has no implementation.
That combination creates misleading success responses and prevents the vault from acting as the durable backing store for native host memory writes. The release must make budget handling honest, add atomic batch writes, and connect the host bridge without letting any partial write or guessed hook contract masquerade as success.
Scope
In scope for this release:
t_64ec5bbdβ make pinned-context budget handling explicit instead of silently truncating.t_c492e539β add atomic batch writes for pinned context and continuity append flows.t_5e06b572β implement the Hermeson_memory_writebridge after verifying the exact host contract.
The cards ship together on branch feat/memory-subsystem-alignment and must be driven one at a time on the shared branch so later workers build on prior commits.
Out of scope
- Replacing the vault-first Markdown/JSONL storage model.
- Adding LLM calls, semantic merging, or provider-specific logic inside the core.
- Rewriting unrelated memory tools, search, dream, hygiene, or recall behavior.
- Changing behavior for callers that stay within current single-operation budgets unless the new response fields are explicitly relevant.
- Dispatching cards from triage during Phase 0.
Chosen approach
Chosen variant: Variant 1 β Shared budget-aware write engine.
Introduce a deterministic core memory-write module that centralizes budget accounting, operation validation, all-or-nothing application, and terminal/idempotent success metadata. Existing pinned-context and continuity writers become consumers of that primitive, and the Hermes on_memory_write hook becomes a thin adapter that maps the verified host payload into the same batch substrate.
I agree with the consultant recommendation. The release is about alignment across memory paths, so duplicating budget and atomicity rules per surface would recreate the drift this release is meant to remove. A shared primitive also preserves the strategic sequencing: budget honesty first, atomic batch substrate second, bridge adapter third.
Design decisions
Centralize budget semantics in core, not MCP or plugin glue.
- The core should expose an explicit outcome for normalized content that exceeds the pinned-context budget.
- Oversized writes must fail as
budget_exceededand must not mutateBrain/pinned.md. - The failure metadata must include operation name, original size, normalized size, allowed budget, persisted size (unchanged/current), and a retry/consolidation hint.
Batch validation happens before mutation.
- An
operationsarray is validated in order against the final projected state. - A malformed operation, invalid replace target, or over-budget final state aborts the whole batch.
- Tests must prove the on-disk store is unchanged when a middle operation fails.
- An
Pinned context owns ordered text operations.
- Preserve existing
read,write,append, andclearbehavior for callers that do not passoperations. - Add an ordered batch mode covering
write,append,clear, and targetedreplacesegment operations. - Return terminal/idempotent success metadata so agents do not repeat successful writes.
- Preserve existing
Continuity owns append batches under one lock.
- Add a batch append function that builds every record first, acquires the month lock once per affected shard, and appends only after validation succeeds.
- Keep single-record append output byte-identical for existing callers.
- If a batch can span months, group by shard deterministically and document the atomicity boundary; prefer same-call validation before any write and tests that cover the expected boundary.
The bridge is host-contract-first.
- Before implementation, verify
on_memory_writeregistration, payload shape, operation names, batch semantics, and success response contract against Hermes source and PRs #48507/#48262. - The plugin handler must be a thin adapter over the shared batch primitive, not an independent writer engine.
- If the host never invokes the hook, behavior remains a no-op with no startup side effects.
- Before implementation, verify
No misleading fallbacks.
- Unknown bridge payloads, invalid operations, partial writes, or budget overflows fail explicitly.
- Do not silently drop fields, guess operation names, or translate unsupported host requests into approximate local writes.
File changes
Expected implementation areas:
src/core/brain/pinned.tsβ budget-aware normalize/apply result, ordered pinned-context operations.src/core/brain/memory-write.tsorsrc/core/brain/memory-write/β shared budget and ordered-operation helper if implementation needs a separate module; otherwise keep the helper private topinned.tsuntil a second consumer requires extraction.src/core/redactor.tsβ keep generic sanitization behavior stable; avoid making global text-field sanitization throw for all callers unless all downstream impact is audited.src/mcp/brain/context-tools.tsβ expose optionaloperationsmode and serialize explicit budget/terminal metadata.src/core/brain/continuity/store.tsβ add atomic batch append substrate while preserving single append behavior.src/core/brain/continuity/types.tsβ add any required typed payload/record inputs without breaking current record shape.plugins/hermes/provider.pyβ implement the verifiedon_memory_writehook onOpenSecondBrainMemoryProvideras the host-facing adapter.plugins/hermes/_base.pyβ keep the local fallbackMemoryProvidersignature aligned with the verified hook contract for non-Hermes tests.plugins/hermes/bridge.pyβ extend the Python-to-TypeScript bridge only if the hook needs a dedicated tool call or typed adapter beyond existingcall_tool.plugins/hermes/__init__.pyβ change only if provider registration/export wiring must expose the new hook differently; no independent write logic belongs here.plugin.yamlandplugins/hermes/plugin.yamlβ keep hook declaration consistent; adjust only if contract verification requires metadata changes.- Tests under
tests/covering budget honesty, pinned batch atomicity, continuity batch atomicity, bridge persistence/no-op behavior, and fallback signature compatibility.
Risks
- Hermes hook contract risk: the live
on_memory_writepayload may differ from assumptions in card text. Mitigation: make contract verification the first step oft_5e06b572and do not code the bridge from guesses. - Atomicity boundary risk: continuity JSONL batches may span month shards. Mitigation: validate all records before writes, group deterministically, and document/test the supported atomicity boundary.
- Compatibility risk: existing agents may expect
brain_pinned_contextsuccess for large input. Mitigation: keep within-budget behavior unchanged and surface explicit machine-readable budget failure for oversized input. - Abstraction risk: a shared engine can become too broad. Mitigation: keep it narrow: budget accounting, operation validation, batch application, and result metadata only.