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
Memory subsystem alignment β implementation plan
Branch: feat/memory-subsystem-alignment
Overall release scope:
t_64ec5bbdβ Make pinned_context budget honest: surface truncation instead of silent data loss.t_c492e539β Add atomic batch (operations array) writes to Open Second Brain writer tools.t_5e06b572β Implement the on_memory_write memory-provider bridge (capture host native memory writes).
Drive these cards one at a time on the shared branch. Each worker must inspect git log and git status before editing, build on commits from prior in-scope cards, and avoid duplicating or conflicting with sibling work.
t_64ec5bbd β Make pinned_context budget honest: surface truncation instead of silent data loss
Files
src/core/brain/pinned.tssrc/core/redactor.tssrc/mcp/brain/context-tools.ts- Focused tests under
tests/for pinned-context budget behavior.
Plan
- Add a pinned-context-specific normalization/budget result instead of relying on the generic
sanitiseTextField(...).slice(0, maxLen)behavior as an unreported success path. - Preserve current behavior for content whose normalized length is at or below
MAX_PINNED_CONTEXT_LEN. - For over-budget write/append input, return an explicit machine-readable budget signal rather than silent success. Prefer a rejected/budget-exceeded result that includes original and normalized sizes, budget, operation, and a consolidation/retry hint.
- Ensure
brain_pinned_contextserializes the budget signal consistently and does not write a partial/truncated value while claiming success. - Keep generic
sanitiseTextFieldstable for unrelated callers unless a full audit proves a narrower change is safe.
Acceptance (passing test)
- A test writes over-budget pinned-context input and asserts:
- the response includes an explicit budget/truncation/rejection signal;
- original and allowed/stored counts are exposed;
- the persisted pinned context is not silently replaced by an unmarked truncated value.
- Existing within-budget write, append, read, and clear tests still pass.
Depends on
- No in-scope card dependency. This should land first because
t_c492e539should use the same budget-honesty semantics for batch mode.
t_c492e539 β Add atomic batch (operations array) writes to Open Second Brain writer tools
Files
src/core/brain/pinned.tssrc/mcp/brain/context-tools.tssrc/core/brain/continuity/store.tssrc/core/brain/continuity/types.ts- Focused tests under
tests/for pinned and continuity batch atomicity.
Plan
- Build on the budget result from
t_64ec5bbd; do not reimplement a separate budget path. - Add an optional ordered
operationsarray mode tobrain_pinned_contextwhile preserving the existing singleoperationparameter behavior. - Support ordered pinned operations for
write,append,clear, and targetedreplacesegments. Validate every operation and the final projected content before writing anything. - Add terminal/idempotent success metadata to writer success responses so agents can stop after a successful call.
- Add continuity batch append support that builds and validates all records before writing, then appends under a single lock acquisition per target shard.
- If continuity batches can span month shards, make the boundary explicit in code comments and tests; do not imply cross-shard atomicity unless the implementation truly guarantees it.
Acceptance (passing test)
- A pinned-context batch test with a malformed middle operation leaves the existing pinned-context file byte-for-byte unchanged.
- A valid pinned-context batch applies operations in order and returns terminal/idempotent success metadata.
- A continuity batch test proves valid records append under the batch path, and an invalid record in the batch leaves the log unchanged for the tested shard.
- Existing single-operation writer tests still pass.
Depends on
t_64ec5bbdshould land first so batch mode reuses the same budget-honesty contract.
t_5e06b572 β Implement the on_memory_write memory-provider bridge (capture host native memory writes)
Files
plugins/hermes/__init__.pyplugin.yamlplugins/hermes/plugin.yaml- Any shared bridge/core adapter module needed to keep plugin glue thin.
src/core/brain/pinned.tsandsrc/core/brain/continuity/store.tsonly through the shared primitives from prior cards.- Focused tests under
tests/for host payload mapping, vault persistence, and no-op behavior.
Plan
- Before coding, verify the exact
on_memory_writecontract from Hermes source and PRs #48507/#48262: hook discovery, function signature, payload fields, operation names, batchoperationsshape, replace/remove semantics, and success response expectations. - Record the verified contract in comments or a small test fixture so future changes do not depend on memory of the external PR.
- Implement the Hermes hook handler as a thin adapter that maps verified host payloads into the shared batch substrate from
t_c492e539. - Persist host memory writes into the vault using the chosen durable representation: continuity record kind and/or pinned-context update as justified by the verified payload semantics.
- Reject unknown or malformed payloads explicitly. Do not guess signatures, ignore unsupported fields silently, or perform partial writes.
- Keep the path no-op when the host does not invoke the hook; plugin startup must not mutate the vault by itself.
Acceptance (passing test)
- A test using a representative verified host payload proves native memory writes land in the vault.
- A batch payload, if supported by Hermes, is applied atomically through the same substrate as
brain_pinned_contextbatch mode. - A malformed or unsupported payload returns an explicit failure and leaves the vault unchanged.
- A no-invocation/no-host path performs no writes.
Depends on
t_64ec5bbdandt_c492e539should land first. The bridge must reuse their budget-honesty and batch-atomicity primitives rather than implementing independent memory-write semantics.