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
24.2 KB
Raw Blame

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 the entitySet --alias path (src/cli/brain/verbs/entity.ts:86-120 semantics), body fold-or-archive decision, sha256Hex(JSON.stringify(plan)) plan hash, applyPlan behind withDestructiveSnapshot (snapshot-gate.ts:374), pruneEntityLabels (label-hygiene.ts:257), inboundReferences check (:156), audit record via src/core/reliability/audit.ts + audit-dirs.ts, quarantine-lane refusal, optional guardEntityMerge over both bodies from src/core/brain/truth/merge-guard.ts:77); tests: new tests/core/brain/entities/page-merge.test.ts on the tests/core/brain/merge.test.ts template (mkdtemp vault, canonical-writer fixtures, toThrow(BrainMergeError) + code), extensions to entities.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, planEntityMerge produces a plan whose steps are alias-on-survivor + fold-or-remove, with entityMergePlanHash stable across two calls on identical input; the plan builder is read-only, so a preview is a byte-no-op on the vault; applyEntityMerge without 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 with rmSync behind the withDestructiveSnapshot recovery 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; every renameSync/unlinkSync sits inside withDestructiveSnapshot or a DESTRUCTIVE_SITES row with a reason >= 60 chars (destructive-site-census green); every new write goes through writeFrontmatterAtomic/atomicWriteFileSync or a categorised exclusion (write-site-census green); the write entry asserts assertVaultIdentityForWrite (vault-guard-census green); page reads go through buildEntityIndex/parseEntityFile with 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 (new merge subcommand in the cmdBrainEntity switch (:59-84): subject resolution accepting BOTH entity-alias-candidate (opt-in, semantic-dedup.ts:48-63 pair id <a>::<b> sorted) and duplicate-entity (entity-checks.ts:112-119) findings; --dry-run preview rendering the plan + plan-hash line; apply requiring --expect-hash <hash> verified before any write, TTY y/N prompt, --force for agents, --json output - shape of verbs/merge.ts:42-79, refusal shape per doctor-exits.ts:98-103); src/cli/brain/help-text.ts (brain entity help row, following the phrase-confirm wording precedent at :1211/:1222); src/cli/command-manifest.ts brain group row; docs/cli-reference.md; tests: tests/cli/brain-entity.test.ts extensions (runCli harness), entities/doctor.entities.test.ts for 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 same merge call without --dry-run, and it requires --expect-hash, refusing with hash-required when it is missing; a stale or mismatched hash refuses before any write with hash-mismatch; with the echoed hash on a TTY it prompts y/N and on --force applies without prompting, while --json or a non-TTY stdin without --force refuses with code consent-required; both doctor finding subjects resolve (a duplicate-entity collision 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; the applier-capability.ts:203-207 fixer table's merge route resolves to the new verb; manifest-completeness and help-surface-parity stay green with the truthful brain entity row.
  • Depends on: Task A1

Task A3: Destination aggregate core reader (t_69fec179)

  • Files: new src/core/brain/notes/write-destinations.ts beside src/core/brain/notes/write-log.ts (query-time fold over listLogDates + readLogDay with since/until day narrowing, reading BOTH BRAIN_LOG_EVENT_KIND.noteWrite and the write-session audit kind; group key = vault-relative target as recorded; per-destination kinds coverage field; agent/device/path/since/until filters; default 7-day window; limit + total_matched; warnings passthrough for unreadable days; tie-stable ordering); tests: new tests/core/brain/notes/write-destinations.test.ts on the write-log.test.ts template (mkdtemp, seed ONLY via appendLogEvent, 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 kinds field that truthfully names which kinds contributed; a destination touched only by a write-session audit event (which emits no note-write) still appears with kinds reflecting 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 and since/until narrow the walk; an unreadable day yields a warning and not an empty group; equal-key rows keep seed order (tie-stable); limit truncates with total_matched reporting 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 (new destinations subcommand, default window, --agent --device --path --since --until --limit --json); src/cli/brain/verbs/index.ts (barrel row beside writes :19 / event-trace :113); src/cli/brain.ts (dispatcher case, switch stays default:-terminated); src/cli/brain/help-text.ts (summary line + VERB_HELP entry); src/cli/command-manifest.ts (:255-256 area); docs/cli-reference.md; src/mcp/brain/query-tools.ts (new read-only tool beside brain_writes :351-443, registered at :968, with pageSlice/cursorOffsetArg :388-427, total_matched, warnings passthrough, reach filtering reachView + view.visible :411-421 so a withheld page moves no count); src/core/search/visibility-surface-registry.ts (row beside brain_writes :498); src/mcp/registry-guard.ts (bounded-summary entry, registry-guard.ts:388-400 pattern); tests: tests/core/brain/event-trace-tool.test.ts + brain-event-trace.test.ts as 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 --json lists 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 report total_matched; every frozen-surface pin is moved exactly once and stays green: brain-tools-parity frozen name-set, tool-probe-catalogue counts, tool-ceiling available_tool_count, agent-scope-matrix classification; 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 lint clean.
  • Depends on: Tasks A1-A4

Task B1: Promote neutralizeSingleLine into untrusted-source (t_ba04a81a)

  • Files: src/core/brain/untrusted-source.ts (export neutralizeSingleLine moved from the duplicated privates at recall-inject.ts:1091 and navmap.ts:66, plus the shared framing constant beside UNTRUSTED_SOURCE_TAG and 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.ts extensions (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. neutralizeSingleLine is exported from untrusted-source.ts and 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 to inject_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 through neutralizeUntrustedText before 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 in Brain/active.md and Brain/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-meter green 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_delimiting is untouched - context-pack flag tests (:440+) and operator-summary/doctor-trust pins stay green; the four existing SessionStart lanes keep passing tests/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; reads Brain/log via readLogDay/listLogDates from log-jsonl.ts, payload.agent top-level :398; filters entry.agent !== self; newest-50 + older count via the buildActivityTimeline limit/total pattern; per-lane line/char cap constant; fail-soft everywhere, exit 0); new cursor module beside hooks/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 via bun 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_*) and hooks/lib/active-context.ts:60-63 (SOURCE_*) if attribution is reported; tests: new tests/hooks/log-catchup.test.ts on the backlog-nudge.test.ts runHook template (Bun.spawn, stdin JSON, homeEnv isolation) with log-shards.write/read.test.ts fixtures; tests/hooks/hooks-json-shape.test.ts covers the new entry; write-site-census row or categorised exclusion for the cursor write.
  • Acceptance: failing test first. Two appendLogEvent calls 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 - and Brain/log is 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:check green); the write-site census pins the cursor write site or its exclusion; attribution, if reported, appears as a context receipt item with a SOURCE_* 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:check green; bun run fmt + bun run lint clean; src/core/brain/notes/write-record.ts untouched (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-level const COLLATOR = new Intl.Collator("en", { numeric: true }) near the listVaultPages site :635; line :692 becomes COLLATOR.compare(a.title.toLowerCase(), b.title.toLowerCase()); doc comment :651 states host independence); tests/core/vault.test.ts (extend describe("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 (toLowerCase kept, no sensitivity change); tests/mcp/mcp.test.ts inherited-order pin (~:598) stays green; the raw readdir helpers and explorer ordering are untouched; no other caller of listVaultPages regresses.
  • Depends on: none

Task C2: Hermes memory_providers entry point (t_dee22e5d)

  • Files: pyproject.toml (add [project.entry-points."hermes_agent.memory_providers"] with open-second-brain = "plugins.hermes"; amend the header comment that says "no CLI entry points"); tests/python/test_hermes_plugin.py (extend HermesLoaderContractTests :96-160 plus a tomllib test parsing pyproject: group present, target importable via importlib.import_module, register attribute resolvable per the root __init__.py:9-16 three-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") exposes register; the loader-contract test passes unchanged semantics (no pre_llm_call hook registered - test_no_pre_llm_call_hook_registered stays green); python -m unittest discover -s tests/python green on Python 3.11; bun run sync-version:check unaffected (PYPROJECT_RE matches only the version); plugin_guard scans the amended files clean; install/hermes.md states that discovery resolves from the wheel (target IS plugins.hermes) but the provider bridge still needs o2b on 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.ts and python -m unittest discover -s tests/python all green; bun run fmt + bun run lint clean; bun run sync-version:check green.
  • Depends on: Tasks C1-C2

Task D1: OKF v0.2 export emission (t_ffdb4fac)

  • Files: src/core/brain/portability/okf.ts (renderIndex :382 adds okf_version: "0.2" to the bundle-root index.md frontmatter; per-page sources: list translated from collectCitations :210-218 - resource REQUIRED: URL as-is, wikilink resolved through the bundle_path map :276-283, neither -> dropped, ambiguous basename resolutions dropped rather than guessed; optional id when the body cites; per-page generated: { by: "open-second-brain/<version>", at } sharing ONE isoSecond() bundle value :449; conservative lifecycle map read off frontmatter status: only (_lifecycle is deliberately not consulted): draft -> draft, deprecated/retired/superseded/archived/terminal -> deprecated, done/closed/resolved and any other or absent status -> stable; manifest schema: "1" kept as-is; redactForEgress stays 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 dialect schema: "1"; every page with citations carries a sources: list whose every entry has resource, and a dangling (unresolvable or ambiguous) citation is dropped, not guessed; every page carries generated: {by, at} with ONE shared at across the bundle; a status: done page exports as stable and a status: archived page 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) and export-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 dialect schema: "1" OR index.md okf_version: "0.2", refuses everything else by name with the existing message shape; the returned manifest preserves the on-disk schema value - :615 stops hardcoding OKF_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 via readOkfBundle :623 and inherits the gate).
  • Acceptance: failing test first. A v0.2 bundle round-trips through import with per-page sources/generated preserved 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.ts export/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 lint clean; 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) and python -m unittest discover -s tests/python all 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)