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.
Actionable-now batch - implementation plan
Feature branch: feat/actionable-now-batch. TDD per task (write the failing test first, then the change), one atomic conventional commit per task, bun run fmt + bun run lint green before every commit. Four lanes run in parallel in separate worktrees; no task depends on a task in another lane. Lane ownership is disjoint - if a task seems to need a file another lane owns, stop and escalate to the integrator instead of editing it.
Census notes for all lanes: tests/core/architecture/write-site-census.test.ts, destructive-site-census, vault-guard-census, entity-read-census, visibility-surface-census and the state-surface census are two-way pins - add or adjust rows in the same commit as the code. CHANGELOG and version are NOT part of any task; osb-pr-prepare handles them.
Task A1: Entity page-merge core module (t_28a8789d)
- Files: new
src/core/brain/entities/page-merge.ts(plan builder over a doctor finding: survivor, old page, alias add via theentitySet --aliaspath (src/cli/brain/verbs/entity.ts:86-120semantics), body fold-or-archive decision,sha256Hex(JSON.stringify(plan))plan hash,applyPlanbehindwithDestructiveSnapshot(snapshot-gate.ts:374),pruneEntityLabels(label-hygiene.ts:257), inboundReferences check (:156), audit record viasrc/core/reliability/audit.ts+audit-dirs.ts, quarantine-lane refusal, optionalguardEntityMergeover both bodies fromsrc/core/brain/truth/merge-guard.ts:77); tests: newtests/core/brain/entities/page-merge.test.tson thetests/core/brain/merge.test.tstemplate (mkdtemp vault, canonical-writer fixtures,toThrow(BrainMergeError)+ code), extensions toentities.label-hygiene.test.ts,entities/write-lane.test.ts,hygiene-apply.test.ts. - Acceptance: failing test first. Given two entity pages of the same category,
planEntityMergeproduces a plan whose steps are alias-on-survivor + fold-or-remove, withentityMergePlanHashstable across two calls on identical input; the plan builder is read-only, so a preview is a byte-no-op on the vault;applyEntityMergewithout a verified hash refuses before any write; with the matching hash it folds the old body into the survivor and then removes the old page file withrmSyncbehind thewithDestructiveSnapshotrecovery point (never a bare delete), adds the alias, retargets only the inbound relation edges, appends the audit record, and claim aggregation afterwards resolves the old name to the survivor with ZERO claim rewrites; a plan naming a quarantine-lane record is refused with a named reason; everyrenameSync/unlinkSyncsits insidewithDestructiveSnapshotor a DESTRUCTIVE_SITES row with a reason >= 60 chars (destructive-site-census green); every new write goes throughwriteFrontmatterAtomic/atomicWriteFileSyncor a categorised exclusion (write-site-census green); the write entry assertsassertVaultIdentityForWrite(vault-guard-census green); page reads go throughbuildEntityIndex/parseEntityFilewith the shared status predicate (entity-read-census green); no new persisted state directory appears, so the state-surface census count is unchanged. - Depends on: none
Task A2: brain entity merge verb with plan-hash accept gate (t_28a8789d)
- Files:
src/cli/brain/verbs/entity.ts(newmergesubcommand in thecmdBrainEntityswitch (:59-84): subject resolution accepting BOTHentity-alias-candidate(opt-in,semantic-dedup.ts:48-63pair id<a>::<b>sorted) andduplicate-entity(entity-checks.ts:112-119) findings;--dry-runpreview rendering the plan +plan-hashline; apply requiring--expect-hash <hash>verified before any write, TTY y/N prompt,--forcefor agents,--jsonoutput - shape ofverbs/merge.ts:42-79, refusal shape perdoctor-exits.ts:98-103);src/cli/brain/help-text.ts(brain entityhelp row, following the phrase-confirm wording precedent at :1211/:1222);src/cli/command-manifest.tsbrain group row;docs/cli-reference.md; tests:tests/cli/brain-entity.test.tsextensions (runCli harness),entities/doctor.entities.test.tsfor the re-run-clean regression. - Acceptance: failing test first.
brain entity merge <keep> <drop> --dry-run --json(the survivor is the FIRST argument) prints the plan and its hash without touching the vault; there is no separate apply subcommand - the apply is the samemergecall without--dry-run, and it requires--expect-hash, refusing withhash-requiredwhen it is missing; a stale or mismatched hash refuses before any write withhash-mismatch; with the echoed hash on a TTY it prompts y/N and on--forceapplies without prompting, while--jsonor a non-TTY stdin without--forcerefuses with codeconsent-required; both doctor finding subjects resolve (aduplicate-entitycollision with the alias-candidate gate off still merges); the doctor message text is unchanged (exact-match verdict matching stays green); a doctor re-run after apply is clean; theapplier-capability.ts:203-207fixer table'smergeroute resolves to the new verb; manifest-completeness and help-surface-parity stay green with the truthfulbrain entityrow. - Depends on: Task A1
Task A3: Destination aggregate core reader (t_69fec179)
- Files: new
src/core/brain/notes/write-destinations.tsbesidesrc/core/brain/notes/write-log.ts(query-time fold overlistLogDates+readLogDaywith since/until day narrowing, reading BOTHBRAIN_LOG_EVENT_KIND.noteWriteand the write-session audit kind; group key = vault-relative target as recorded; per-destinationkindscoverage field;agent/device/path/since/untilfilters; default 7-day window; limit +total_matched; warnings passthrough for unreadable days; tie-stable ordering); tests: newtests/core/brain/notes/write-destinations.test.tson thewrite-log.test.tstemplate (mkdtemp, seed ONLY viaappendLogEvent, never hand-written logs). - Acceptance: failing test first. Seeding both kinds across two days and two agents, the fold returns one row per destination path with the contributing agents/devices and a
kindsfield that truthfully names which kinds contributed; a destination touched only by a write-session audit event (which emits no note-write) still appears withkindsreflecting that; a destination touched by no recorded kind (slug-derived/fully-derived binding sites) never appears, and the result's coverage note says derived sites emit nothing; the default window covers 7 days andsince/untilnarrow the walk; an unreadable day yields a warning and not an empty group; equal-key rows keep seed order (tie-stable); limit truncates withtotal_matchedreporting the pre-truncation count; nothing is written to disk during a query (no persisted table, state-surface census unchanged). - Depends on: none
Task A4: Destination aggregate CLI + MCP exposure and registrations (t_69fec179)
- Files:
src/cli/brain/verbs/writes.ts(newdestinationssubcommand, default window,--agent --device --path --since --until --limit --json);src/cli/brain/verbs/index.ts(barrel row besidewrites:19 /event-trace:113);src/cli/brain.ts(dispatcher case, switch staysdefault:-terminated);src/cli/brain/help-text.ts(summary line +VERB_HELPentry);src/cli/command-manifest.ts(:255-256 area);docs/cli-reference.md;src/mcp/brain/query-tools.ts(new read-only tool besidebrain_writes:351-443, registered at :968, withpageSlice/cursorOffsetArg:388-427,total_matched, warnings passthrough, reach filteringreachView+view.visible:411-421 so a withheld page moves no count);src/core/search/visibility-surface-registry.ts(row besidebrain_writes:498);src/mcp/registry-guard.ts(bounded-summary entry,registry-guard.ts:388-400pattern); tests:tests/core/brain/event-trace-tool.test.ts+brain-event-trace.test.tsas CLI/MCP templates,tests/mcp/mcp.test.ts,tests/mcp/brain-tools-parity.test.ts,tests/mcp/agent-scope-matrix.test.ts,tests/helpers/tool-probe-catalogue.ts,tests/core/install/tool-ceiling.test.ts. - Acceptance: failing test first.
o2b brain writes destinations --agent X --jsonlists the same rows the core reader returns; the MCP tool returns identical totals for the same query; a page withheld by reach filtering moves no row and no total; limit/cursor round-trips reporttotal_matched; every frozen-surface pin is moved exactly once and stays green:brain-tools-parityfrozen name-set,tool-probe-cataloguecounts,tool-ceilingavailable_tool_count,agent-scope-matrixclassification; the VISIBILITY_SURFACE_REGISTRY row and the two-way visibility-surface-census pin land in the same commit; the registry-guard bounded-summary covers the new tool; manifest-completeness and help-surface-parity stay green; the tool is read-only (no write-site census triggered). - Depends on: Task A3
Task A5: Lane A targeted suites green
- Files: none (verification only).
- Acceptance:
bun run test tests/core/brain/entities/ tests/core/brain/notes/write-destinations.test.ts tests/core/brain/notes/write-log.test.ts tests/cli/brain-entity.test.ts tests/core/brain/event-trace-tool.test.ts tests/cli/brain-event-trace.test.ts tests/mcp/mcp.test.ts tests/mcp/brain-tools-parity.test.ts tests/mcp/agent-scope-matrix.test.ts tests/core/architecture/visibility-surface-census.test.ts tests/core/architecture/write-site-census.test.ts tests/core/architecture/destructive-site-census.test.ts tests/core/architecture/vault-guard-census.test.ts tests/core/architecture/entity-read-census.test.ts tests/cli/manifest-completeness.test.ts tests/cli/help-surface-parity.test.ts(or the repo's equivalent filter invocation) all green;bun run fmt+bun run lintclean. - Depends on: Tasks A1-A4
Task B1: Promote neutralizeSingleLine into untrusted-source (t_ba04a81a)
- Files:
src/core/brain/untrusted-source.ts(exportneutralizeSingleLinemoved from the duplicated privates atrecall-inject.ts:1091andnavmap.ts:66, plus the shared framing constant besideUNTRUSTED_SOURCE_TAGand a lighter framing-header helper);src/core/brain/recall-inject.ts+src/core/brain/navmap.ts(import refactor ONLY - byte-identical behaviour); tests:tests/core/brain/untrusted-source.test.tsextensions (patterns at :44, :108, :145; close-count at :139, :160),tests/core/brain/context-guard.test.ts(:9, :97) still green. - Acceptance: failing test first.
neutralizeSingleLineis exported fromuntrusted-source.tsand both former private copies are gone (imports, not duplicates); the framing-header helper emits a records-not-instructions header one line long; recall-inject and navmap behaviour is byte-identical (their existing fence tests pass unmodified); the module exports compile without pulling hook-only dependencies into core. - Depends on: none
Task B2: Guard the unguarded SessionStart injection lanes (t_ba04a81a)
- Files:
hooks/lib/active-context.ts(guard the active body push :278-283 and lessons push :284-291 at the assembly chokepoint :213-237 BEFORE the meter push; lighter framing header, not a full fence; runtime notices :223 stay trusted; standing/scoped rules stay trusted-with-precedence-header);src/core/brain/policy/blocks/active.ts(fence/header overhead charged toinject_budget_chars, recall-inject.ts:972 fenceOverhead precedent, so the tier ladder does not evict sections);src/core/brain/gaps/gap-loop.ts(neutralizeSingleLine(task.topic)at :387 + full-fence framing header on the agenda block :382-391); the answer-quote-check module (route annotation spans throughneutralizeUntrustedTextbefore the collapse at :730-732, framing line in the annotation :771-784); tests:tests/hooks/active-inject.test.ts(runHook :41-60; plant a hostile instruction line - imperative prose that reads as overriding earlier context, worded so the hermes install scanner does not match it - plus control chars inBrain/active.mdandBrain/lessons.md, assert framing header + neutralized text),tests/hooks/active-inject-meter.test.ts(guarded-text byte attribution),gap-loop.test.ts:340,answer-quote-check.test.ts. - Acceptance: failing test first. A planted instruction line in active or lessons reaches the payload with control/bidi characters stripped, single-line neutralized, under a framing header - never as a bare line; the meter attributes the GUARDED bytes (exact string match still resolves,
active-inject-metergreen with updated expectations); the tier ladder does not evict active/lessons sections because of the header (budget test pins the charged overhead); gap-agenda topics are neutralized and the agenda block is fenced; answer-quote-check annotations contain no raw control characters and carry the framing line;untrusted_source_delimitingis untouched - context-pack flag tests (:440+) andoperator-summary/doctor-trustpins stay green; the four existing SessionStart lanes keep passingtests/hooks/hooks-json-shape.test.ts. - Depends on: Task B1
Task B3: Cross-agent catch-up SessionStart lane (t_3b44cd9a)
- Files: new
hooks/log-catchup.ts(own process, name-based dispatch - no registry edit; readsBrain/logviareadLogDay/listLogDatesfromlog-jsonl.ts,payload.agenttop-level :398; filtersentry.agent !== self; newest-50 + older count via thebuildActivityTimelinelimit/total pattern; per-lane line/char cap constant; fail-soft everywhere,exit 0); new cursor module besidehooks/lib/backlog-nudge-state.ts((date, shardId, line)watermark in the derived store<vault>/.open-second-brain/, overwrite-only atomic write, derived-dir-symlink guard, fail-soft read, un-synced);hooks/hooks.json(one opt-in SessionStart entry) + codex mirror viabun run sync-plugin-mirrors;hooks/README.md("What the hooks do" row); config key for the opt-in and the agent identity (device-id fallback);src/core/brain/context-receipts.ts(RECEIPT_ITEM_*) andhooks/lib/active-context.ts:60-63(SOURCE_*) if attribution is reported; tests: newtests/hooks/log-catchup.test.tson thebacklog-nudge.test.tsrunHook template (Bun.spawn, stdin JSON, homeEnv isolation) withlog-shards.write/read.test.tsfixtures;tests/hooks/hooks-json-shape.test.tscovers the new entry; write-site-census row or categorised exclusion for the cursor write. - Acceptance: failing test first. Two
appendLogEventcalls with distinct agents, then run the hook as agent B: B receives exactly agent A's lines since B's cursor - newest 50 plus an older-count when more than 50 - andBrain/logis byte-identical afterwards (read-only lane, distinct from session-capture's lifecycle event); a second run with no new lines emits nothing; the cursor survives as(date, shardId, line)and a same-second line in a different shard is not skipped; a missing/corrupt cursor fails soft and the lane still exits 0; the lane is OFF until the config key is set, and self-authored lines are filtered by the config-resolved agent name with device-id fallback; the codex mirror is regenerated (sync-plugin-mirrors:checkgreen); the write-site census pins the cursor write site or its exclusion; attribution, if reported, appears as a context receipt item with aSOURCE_*provenance. - Depends on: Task B1
Task B4: Lane B targeted suites green
- Files: none (verification only).
- Acceptance:
bun run test tests/hooks/ tests/core/brain/untrusted-source.test.ts tests/core/brain/context-guard.test.ts tests/core/brain/gaps/gap-loop.test.ts tests/core/brain/policy/ tests/core/brain/context-receipts.test.ts tests/core/architecture/write-site-census.test.ts(or the repo's equivalent filter invocation) all green;bun run sync-plugin-mirrors:checkgreen;bun run fmt+bun run lintclean;src/core/brain/notes/write-record.tsuntouched (git diff --exit-code -- src/core/brain/notes/write-record.ts). - Depends on: Tasks B1-B3
Task C1: Fixed-locale numeric collator for listVaultPages (t_d8e7320f)
- Files:
src/core/vault.ts(module-levelconst COLLATOR = new Intl.Collator("en", { numeric: true })near thelistVaultPagessite :635; line :692 becomesCOLLATOR.compare(a.title.toLowerCase(), b.title.toLowerCase()); doc comment :651 states host independence);tests/core/vault.test.ts(extenddescribe("listVaultPages"):461-531). - Acceptance: failing test first. Pages titled "Cafe", "Café", "note 1", "note 2", "note 10" return in exactly that order (numeric: "note 2" before "note 10"; "Café" grouped beside "Cafe") regardless of host locale; case-insensitivity is preserved (
toLowerCasekept, nosensitivitychange);tests/mcp/mcp.test.tsinherited-order pin (~:598) stays green; the raw readdir helpers and explorer ordering are untouched; no other caller oflistVaultPagesregresses. - Depends on: none
Task C2: Hermes memory_providers entry point (t_dee22e5d)
- Files:
pyproject.toml(add[project.entry-points."hermes_agent.memory_providers"]withopen-second-brain = "plugins.hermes"; amend the header comment that says "no CLI entry points");tests/python/test_hermes_plugin.py(extendHermesLoaderContractTests:96-160 plus a tomllib test parsing pyproject: group present, target importable viaimportlib.import_module,registerattribute resolvable per the root__init__.py:9-16three-branch loader contract);install/hermes.md(name the pip/entry-point discovery path and the PATH/checkout caveat). - Acceptance: failing test first. tomllib (stdlib 3.11) parses the entry-point group and
importlib.import_module("plugins.hermes")exposesregister; the loader-contract test passes unchanged semantics (no pre_llm_call hook registered -test_no_pre_llm_call_hook_registeredstays green);python -m unittest discover -s tests/pythongreen on Python 3.11;bun run sync-version:checkunaffected (PYPROJECT_RE matches only the version); plugin_guard scans the amended files clean;install/hermes.mdstates that discovery resolves from the wheel (target ISplugins.hermes) but the provider bridge still needso2bon PATH or a checkout - "zero-config" claimed only for checkout/PATH contexts. - Depends on: none
Task C3: Lane C targeted suites green
- Files: none (verification only).
- Acceptance:
bun run test tests/core/vault.test.ts tests/mcp/mcp.test.tsandpython -m unittest discover -s tests/pythonall green;bun run fmt+bun run lintclean;bun run sync-version:checkgreen. - Depends on: Tasks C1-C2
Task D1: OKF v0.2 export emission (t_ffdb4fac)
- Files:
src/core/brain/portability/okf.ts(renderIndex:382 addsokf_version: "0.2"to the bundle-root index.md frontmatter; per-pagesources:list translated fromcollectCitations:210-218 -resourceREQUIRED: URL as-is, wikilink resolved through thebundle_pathmap :276-283, neither -> dropped, ambiguous basename resolutions dropped rather than guessed; optionalidwhen the body cites; per-pagegenerated: { by: "open-second-brain/<version>", at }sharing ONEisoSecond()bundle value :449; conservative lifecycle map read off frontmatterstatus:only (_lifecycleis deliberately not consulted):draft-> draft, deprecated/retired/superseded/archived/terminal -> deprecated, done/closed/resolved and any other or absent status -> stable; manifestschema: "1"kept as-is;redactForEgressstays in-module); tests:tests/core/brain/portability/okf.test.ts(new v0.2 emission cases: sources with resource, generated block, dangling dropped, lifecycle conservative, determinism). - Acceptance: failing test first. An exported bundle's index.md declares
okf_version: "0.2"and the manifest still carries the dialectschema: "1"; every page with citations carries asources:list whose every entry hasresource, and a dangling (unresolvable or ambiguous) citation is dropped, not guessed; every page carriesgenerated: {by, at}with ONE sharedatacross the bundle; astatus: donepage exports as stable and astatus: archivedpage as deprecated (never the reverse); the determinism test passes with the shared-timestamp decision it pins (whole-bundle byte equality modulo the single generated instant);export-redaction.test.ts(:133, :205) andexport-identifier-integrity.test.ts(:91, :135) stay green; the egress census is unchanged (no new registry entry; the verb module is not split). - Depends on: none
Task D2: OKF importer dual acceptance + downstream fixtures (t_ffdb4fac)
- Files:
src/core/brain/portability/okf.ts(readOkfBundle:570 gate :584-588 accepts dialectschema: "1"OR index.mdokf_version: "0.2", refuses everything else by name with the existing message shape; the returned manifest preserves the on-disk schema value - :615 stops hardcodingOKF_SCHEMA_VERSION;importOkfBundle:818 /importFrontmatter:786 /FOREIGN_MACHINERY_KEYS:695 tolerate the v0.2 per-page keys);tests/core/brain/portability/okf.test.ts(import cases: v0.2 accepted beside "1", unknown refused by name, on-disk schema preserved in the manifest, the ambiguous-basename fixture :157-163 and the "999" refusal :544-552 still hold);tests/core/brain/portability/knowledge-pack.test.ts(inline OkfManifest fixture ripples :282);tests/cli/okf-cli.test.ts(:32+); a pack-install v0.2 half (install re-parses viareadOkfBundle:623 and inherits the gate). - Acceptance: failing test first. A v0.2 bundle round-trips through import with per-page
sources/generatedpreserved as foreign-but-tolerated machinery; a dialect bundle imports exactly as before (round-trip cases :179-242 green unmodified); a bundle with neither marker is refused by name; the manifest returned for a v0.2 bundle reports its own on-disk declaration, not a hardcoded value; a sealed knowledge-pack half exported pre-change still installs (dual acceptance keeps old packs importable) and a v0.2 half installs too;okf-cli.test.tsexport/import flows green. - Depends on: Task D1
Task D3: Lane D targeted suites green
- Files: none (verification only).
- Acceptance:
bun run test tests/core/brain/portability/ tests/cli/okf-cli.test.ts tests/core/install/(or the repo's equivalent filter invocation) all green;bun run fmt+bun run lintclean; the determinism normalization decision from D1 is pinned by a test comment naming both normalized fields if both are normalized. - Depends on: Tasks D1-D2
Task I1: Cross-lane integration gates (integrator)
- Files: only collision-resolution edits; census registration review across lanes.
- Acceptance:
bun run fmt,bun run lint,bun run sync-plugin-mirrors:check,bun run sync-version:check, the lanes' targeted suites, then the full suite (bun run test) andpython -m unittest discover -s tests/pythonall green on the integrated branch; every census obligation in design.md is verifiably registered exactly once (destructive/write/vault-guard/entity-read censuses and manifest-completeness from Lane A; visibility-surface two-way pin, registry-guard bounded summary, frozen MCP pins from Lane A; cursor write-site row or exclusion, hooks-json shape, codex mirror from Lane B; plugin_guard-clean pyproject from Lane C; egress-census-unchanged from Lane D); no file owned by two lanes was edited by both; CHANGELOG and version untouched (osb-pr-prepare's job). - Depends on: Tasks A5, B4, C3, D3 (cross-lane by design; this is the integrator task)