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.
Dated commitments, capture to surface - implementation plan
Branch: feat/dated-commitments (already checked out in the run worktree; never create or switch branches). Version target: 1.90.0 -> 1.91.0 (minor: new MCP tools are a frozen-surface change). Every task below is TDD: write the named acceptance test first, run it, watch it fail with the expected error, implement until green, format and lint, commit as one conventional commit per task.
Pinned cross-lane contract
Lanes A and B are parallel. They agree on the following names TODAY; no lane may rename or reshape them. Lane A task A1 commits this contract first; Lane B tasks B2 and B4 import it and must not edit any Lane A file.
- Path constants,
src/core/brain/path-constants.ts(besideBRAIN_OBLIGATIONS_RELat line 49):export const BRAIN_PLEDGES_REL = posix.join(BRAIN_ROOT_REL, "pledges");
- Path helpers,
src/core/brain/paths.ts(obligations pattern, lines 504-517):export function pledgesDir(vault: string): stringexport function pledgesArchiveDir(vault: string): stringexport function pledgePath(vault: string, slug: string): string
- Relation vocabulary,
src/core/graph/relation-vocab.ts:export const PROMISED_TO_RELATION = "promised_to";added toDEFAULT_RELATION_TYPES(one-line data-driven extension).
- Core page family,
src/core/brain/pledges.ts(mirrorsobligations.ts):export class PledgeError extends Error {}andexport function noPledgeError(slug: string): PledgeErrorexport interface PledgePage { readonly slug: string; readonly title: string; readonly text: string; readonly due: string; readonly createdAt: string; readonly source: string; readonly evidence: ReadonlyArray<string>; readonly counterparties: ReadonlyArray<string>; readonly fulfilled: string | null; readonly agent: string; readonly notes: string; readonly path: string }export interface AddPledgeInput { readonly title: string; readonly due: string; readonly source: string; readonly evidence: ReadonlyArray<string>; readonly text?: string; readonly counterparties?: ReadonlyArray<string>; readonly notes?: string; readonly agent: string; readonly now?: Date }export function addPledge(vault: string, input: AddPledgeInput): PledgePage- validatesdueviavalidateIsoDate, refuses an empty evidence list, refuses any quote that does not occur in the source page (quote-span containment), refuses a taken slug, writes atomically underassertVaultIdentityForWrite, renders bare frontmatter keystitle, created_at, due, source, evidence, promised_to, fulfilled, agent.export function fulfillPledge(vault: string, input: { slug: string; date?: string; now?: Date }): PledgePageexport function showPledge(vault: string, input: { slug: string; readable?: (rel: string) => boolean }): PledgePage | null- a withheld page answers null.export function pledgeExists(vault: string, slug: string): booleanexport interface PledgeListItem { readonly slug: string; readonly title: string; readonly due: string; readonly overdue: boolean; readonly daysUntilDue: number; readonly counterparties: ReadonlyArray<string>; readonly fulfilled: string | null; readonly source: string; readonly path: string }export function listPledges(vault: string, input: { now: Date; readable?: (rel: string) => boolean; includeFulfilled?: boolean }): ReadonlyArray<PledgeListItem>- sorted by due then slug; open pledges only unlessincludeFulfilled.export function removePledge(vault: string, input: { slug: string }): { slug: string; archivePath: string }- archive rename with collision suffix, the obligations pattern.
- Intake,
src/core/brain/pledge-intake.ts(mirrorsextract-intake.tsdiscipline):export class PledgeIntakeError extends Error {}export interface PledgeIntakeItem { readonly title: string; readonly due: string; readonly evidence: ReadonlyArray<string>; readonly text?: string; readonly counterparties?: ReadonlyArray<string> }export interface PledgeIntakeInput { readonly source: string; readonly pledges: ReadonlyArray<PledgeIntakeItem> }export interface PledgeIntakeResult { readonly created: ReadonlyArray<string>; readonly duplicates: ReadonlyArray<string>; readonly reanchored: ReadonlyArray<string>; readonly staleEdges: ReadonlyArray<string>; readonly unanchoredCounterparties: ReadonlyArray<string> }- pages are keyed onslugify(title), so two pledges that share a title cannot both exist: the (title, due, source) hash only classifies repeats, and a second pledge with the same title but a different due/source is refused with "slug already held by a different pledge" (titles are unique among active pledges). The batch is capped by name (MAX_INTAKE_PLEDGES = 100pledges per intake,MAX_INTAKE_COUNTERPARTIES = 32counterparty names per pledge,MAX_INTAKE_COUNTERPARTY_NAME_LENGTH = 200characters per name); a batch over a cap refuses whole.export function intakePledges(vault: string, input: PledgeIntakeInput, opts: { agent: string; now: Date; readable?: (rel: string) => boolean }): PledgeIntakeResult- validates EVERY item (including quote containment and source readability) before writing anything; identity = sha256 first 12 hex over the normalized(title, due, source)triple; same identity plus same normalized payload is a reported duplicate no-op, same identity plus different payload throws a namedPledgeIntakeErrormismatch; counterparty names anchored server-side against canonical-scope entities (entityStatusInScope+ the shared anchoring kernel); unanchored names are reported and stored nowhere; re-posting after the entity registers adds the edge (re-anchor arm); a stored edge the readable canonical registry can no longer reproduce is reported understaleEdgesand the page is left byte-identical - an edge that was valid when computed is not the caller's to delete, and the re-anchor arm does not grow a new edge beside a dead one.
- MCP tools,
src/mcp/brain/pledge-tools.ts, exported asexport const PLEDGE_TOOLS: ReadonlyArray<ToolDefinition>and concatenated intoBRAIN_TOOLSinsrc/mcp/brain-tools.ts:brain_pledge- operationsadd | fulfill | list | show | remove; schema mirrorsbrain_obligation(additionalProperties: false,previewBudget: MCP_PREVIEW_BUDGET, reach viareadableAtContextReachOrUndefined(ctx), vault-path-safe responses throughsrc/mcp/vault-path-field.ts).brain_intake_pledges- fieldssource(required),pledges(required array),agent(optional); malformed payloads surface asMCPError(INVALID_PARAMS, "brain_intake_pledges: ...")with typed errors preserved (wrapToolErrors).
- Config surface,
src/core/config.ts(Lane B):export function resolveCounterpartyBriefEnabled(configPath?: string): boolean-resolveConfigFlag("OPEN_SECOND_BRAIN_COUNTERPARTY_BRIEF_ENABLED", "counterparty_brief_enabled", configPath), default off.export function resolveCounterpartyBriefTriggers(configPath?: string): ReadonlyArray<string>- machine-local main-config keycounterparty_brief_triggers; the shipped reader takes a COMMA-SEPARATED STRING (config.ts:903-913), so[a, b]is real YAML list syntax the flat config parser cannot represent and answers[], keeping the brief inert (a bracket-shaped value is malformed, not a token). Tokens are NFC-normalized and trimmed; absent, blank or malformed answers[].export function resolveEntityFactsContextPack(configPath?: string): boolean-resolveConfigFlag("OPEN_SECOND_BRAIN_ENTITY_FACTS_CONTEXT_PACK", "entity_facts_context_pack", configPath), default off (theresolveDensityRankingContextPacktwin, config.ts:852).
- entity_facts pack option,
src/core/brain/context-pack.ts+src/mcp/brain/pack-tools.ts(Lane B):readonly entityFacts?: booleaninContextPackOptions; conditional report memberreadonly entityFacts?: ContextPackEntityFactsReportinContextPackReport, whereexport interface ContextPackEntityFactsReport { readonly entities: ReadonlyArray<{ readonly entityId: string; readonly name: string; readonly itemIds: ReadonlyArray<string> }> }(canonical-scope entities anchored from the pack query, cap 3 entities, item ids drawn only from already-kept candidates, entity pages failing the caller's view treated as absent); conditional output keyentity_factsin the tool projection. Off, every default pack is byte-identical.
- Injection ledger,
hooks/lib/injection-ledger.ts(Lane B):export function readBriefDelivered(vault: string, sessionId: string, nowMs?: number): string | null/export function recordBriefDelivered(vault: string, sessionId: string, entityId: string, nowMs?: number): boolean- thereadRecallInjected/recordRecallInjectedpattern, keyed by the whole brief (not a per-entity set), gated byisRealSessionId, with the ledger's standard TTL and a failed record answeringfalse(the hook treats that as a possible one-brief repeat, never a reason to withhold a brief it already printed).
- Brief core,
src/core/brain/counterparty-brief.ts(Lane B):export interface CounterpartyBriefItem { readonly date: string; readonly text: string; readonly sourceRel: string }export interface CounterpartyBrief { readonly entityId: string; readonly entityName: string; readonly items: ReadonlyArray<CounterpartyBriefItem>; readonly skippedReads: number; readonly notices: ReadonlyArray<DegradationNotice> }(skippedReadscounts a preference page the walk could not read - counted, never swallowed - andnoticescarries one typed degradation notice per such page;CounterpartyBriefItem.dateis""for an undated preference and renders asundated)export function buildCounterpartyBrief(vault: string, input: { text: string; triggers: ReadonlyArray<string>; now: Date; readable?: (rel: string) => boolean; itemLimit?: number }): CounterpartyBrief | CounterpartyBriefAbstention- abstains with a typed reason (export type CounterpartyBriefAbstention = { readonly abstain: "no_trigger" | "no_match" | "ambiguous" }) unless triggers are non-empty AND at least one trigger token occurs in the text AND exactly one canonical-scope entity matches by name or alias: an empty trigger list or a prompt carrying no trigger token abstains asno_trigger, zero canonical-scope matches asno_match, several asambiguous; items: open pledges promised to the entity (due-sorted, fromlistPledges) then recent non-private preference pages whose bodies anchor the entity, bounded walk with named-constant caps (DEFAULT_BRIEF_ITEM_LIMIT = 3, a named char budget, a named page-read cap); a page whosevisibility:carries the reserved token is excluded regardless of reach; withheld pages contribute nothing and are not counted.export function renderCounterpartyBrief(brief: CounterpartyBrief): string-""when the item list is empty (the hook then emits nothing).
Shared-module-first instruction (both lanes)
Lane A executes A1 as the first implementation commit of the wave and nothing else before it. Lane B executes B1 immediately (config resolvers touch no Lane A file), then waits for A1 before B2. Neither lane edits a file owned by the other lane; if a task seems to need a cross-lane file, the lanes extend the pinned contract instead. Lane C runs only after A and B are both complete.
Lane A - substrate: pledge family, intake, projection, CRUD (t_da8673aa)
A1: pledge page family core
- Files:
src/core/brain/path-constants.ts,src/core/brain/paths.ts,src/core/graph/relation-vocab.ts,src/core/brain/pledges.ts,tests/core/brain/pledges.test.ts,tests/core/graph/relation-vocab.test.ts(extend the vocabulary pin deliberately). - Acceptance (red-first):
tests/core/brain/pledges.test.tsfails with "Cannot find module .../pledges.ts"; then passes: mkdtemp vault per test with an injectedNOWconstant (thetests/core/brain/obligations.test.tsfixture pattern); parse/render round-trip;addPledgerefuses a taken slug, a non-ISO due, an empty evidence list, and a quote absent from the source page (each refusal named);fulfillPledgestamps the date;listPledgessorts by due then slug with overdue flag anddaysUntilDueboundaries (yesterday/today/tomorrow); a hand-edited frontmatter date soft-parses likeparseIsoDate;removePledgearchives with a collision-suffixed name. - Depends on: none. This is the wave's first implementation commit.
A2: extraction intake
- Files:
src/core/brain/pledge-intake.ts,tests/core/brain/pledge-intake.test.ts. - Acceptance (red-first):
tests/core/brain/pledge-intake.test.tsfails on the missing module; then passes: an intake containing one invalid item writes NO page (validate before write, no partials); duplicate no-op reports the slug underduplicates; same identity with a changed payload throws the named mismatch; counterparty names anchor topromised_toentity ids through a fixture registry and appear in the page frontmatter; an unanchored name lands inunanchoredCounterpartiesand is absent from frontmatter; re-post after the entity registers moves the pledge toreanchored; areadablepredicate that refuses the source page refuses the whole intake. - Depends on: A1.
A3: MCP tools
- Files:
src/mcp/brain/pledge-tools.ts,src/mcp/brain-tools.ts,tests/mcp/pledge-tools.test.ts. - Acceptance (red-first):
tests/mcp/pledge-tools.test.tsfails because the tool names are absent from the table; then passes: both tools appear inbuildToolTableoutput; schemas reject unknown properties (additionalProperties: false);brain_pledgeadd/fulfill/list/show/remove behave through the handler with a minimalServerContext;listhonors the overdue filter and the readable predicate;brain_intake_pledgesmapsPledgeError/PledgeIntakeErrortoINVALID_PARAMSwith the error name preserved and never wraps an already-typedMCPErrortwice. - Depends on: A1, A2.
A4: reach behavior
- Files:
tests/mcp/pledge-reach.test.ts. - Acceptance (red-first): the suite fails until the reach fixture proves the contract; then passes: two-vault fixture via
tests/helpers/reach-log-fixture.ts(buildReachLogFixture,maskVolatile,reachServer); below local reach a withheld pledge page answersshowas absent (present: falsesemantics), drops fromlist, and refusesfulfill/removewith the sameno pledgeerror an absent slug gets, with a local control proving the page exists; the archive name stays out of a withheldremoveanswer. - Depends on: A3.
A5: tool-surface census registrations (card A checklist, items 1-7 and 10-15 of the recon census)
- Files:
tests/mcp/brain-tools-parity.test.ts(docblock history entry plus the frozen name-set pin picking up both tools),src/core/search/visibility-surface-registry.ts(onecoveredrow per new tool,brain_obligationrow at :810 as the wording template),tests/core/architecture/visibility-surface-census.test.ts(sweep population gains the defining file, history count note),tests/core/architecture/write-site-census.test.ts(categorized exclusion entry for the archive rename plus the pinned direct-row count bump in the docblock history),src/core/brain/destructive-sites.tsplustests/core/architecture/destructive-site-census.test.ts(entry with recovery pointer, pinned-count docblock bump),tests/helpers/tool-probe-catalogue.ts,tests/mcp/agent-scope-matrix.test.ts,tests/mcp/visibility-matrix.test.ts(one invocation recipe and exactly-one classification per new tool),tests/core/architecture/vault-path-census.test.ts(no change expected; run to confirm responses use the vault-path field),tests/core/architecture/import-cycles.test.ts(run to confirm the new modules stay acyclic). - Acceptance: each named census suite passes after its deliberate edit; any equality-pinned count is bumped in the same commit as its entry;
bun test tests/core/architecture tests/mcp/brain-tools-parity.test.tsis green. - Depends on: A3 (rows name real tools), A1 (write and archive sites exist).
A6: today dashboard section
- Files:
src/core/brain/today-dashboard.ts,tests/core/brain/today-dashboard.test.ts(extend),src/mcp/brain/brief-tools.tsand its today-view test (toolBrainTodayat brief-tools.ts:581 embeds the whole dashboard, so the projection gains apledgesmember besideobligationsand the text renders the new section),tests/mcp/today-open-loops-reach.test.ts(extend for the withheld-pledge case). - Acceptance (red-first): the dashboard test fails on the missing section; then passes: the section-name union gains
"pledges"; the section renders due-sorted open pledges with overdue and days-until-due, inside its own try/catch (a throwing builder yields an explicit error entry, not a silently empty section);totalsgainspledgesTotalandpledgesOverduederived from the already-built section (no second scan); thereadablepredicate removes withheld pledge pages before totals; empty vault renders an empty section with no error;brain_brief view=todayreturns thepledgesmember and the section text, honoring the same readable predicate. - Depends on: A1.
Lane B - delivery: entity_facts pack section and the counterparty brief (t_43b0a379)
B1: config resolvers
- Files:
src/core/config.ts,tests/core/config-counterparty-brief.test.ts(new, followingtests/core/config-recall-inject.test.ts), plus theresolveEntityFactsContextPackcases in the same new suite. - Acceptance (red-first): the suite fails on the missing resolvers; then passes: default off with no config; env override wins; a
counterparty_brief_triggerslist is read, trimmed and normalized; absent or malformed lists answer[];entity_facts_context_packdefaults off with the env override honored. No_brain.yamltemplate change is needed (machine-local keys; the config-template ratchet does not apply - asserted by runningtests/core/brain/config-template-ratchet.test.tsunchanged). - Depends on: none. Runs as Lane B's first commit, in parallel with A1.
B2: counterparty brief core
- Files:
src/core/brain/counterparty-brief.ts,tests/core/brain/counterparty-brief.test.ts. - Acceptance (red-first): the suite fails on the missing module; then passes (fixture vault with pledges from A1, preference pages, and a small canonical entity registry): at most
DEFAULT_BRIEF_ITEM_LIMITitems, each carrying its source path and a date (a pledge's due date or the day a preference page was created - a preference with no calendar date is an undated item that sorts last and rendersundated); a page whose visibility carries the reserved token never surfaces, even though the hook runs locally; an item drawn from two source pages is dropped when their token intersection is empty (strictest-visibility semantics); an empty result renders""; abstention on zero matches, on multiple entity matches, on an empty trigger list, and on prompts containing no trigger token; the page-read caps bound both walks in the vault's stable (code-unit) name order BEFORE the recency/due sort, so past the cap the globally newest preferences or soonest-due pledges can fall outside the window; pledges promised to the entity sort before preference facts; areadablepredicate removes pages before anything counts them (identical-to-absent: no counts, no names). - Depends on: A1 (imports
listPledgesandPledgeListItemonly), B1.
B3: entity_facts pack section
- Files:
src/core/brain/context-pack.ts,src/mcp/brain/pack-tools.ts,tests/core/brain/context-pack-entity-facts.test.ts(new, sibling of the seven context-pack suites),tests/mcp/context-pack-tool.test.ts(extend for the config-key seam and theentity_factsoutput projection). - Acceptance (red-first): the new suite fails on the missing option; then passes: without the option the pack is byte-identical to before (snapshot comparison); with it, the report carries
entityFactsentries only for canonical-scope entities anchored from the query, each listing only ids already present initems; a quarantined entity never appears; an entity page that fails the caller's view is treated as absent (its rollup is dropped silently, nothing counts it); at remote reach the section respects the same view the items do; the tool emitsentity_factsonly when the config key resolves on; the other threepackContextcallers are untouched (their suites stay green unchanged). - Depends on: B1 only (no dependency on Lane A; ships independently per the validator comment).
B4: counterparty brief hook
- Files:
hooks/counterparty-brief.ts,hooks/hooks.json(UserPromptSubmit row, exact existing command shape:$CLAUDE_PLUGIN_ROOT,/scripts/o2b-hook,command -v o2b-hook,exit 0,timeout: 10, statusMessage),hooks/README.md(table row documenting the flag and the triggers requirement),src/core/install/grok-asset.ts(register the hook or declare why not, per the parity test contract),plugins/codex/hooks/hooks.json(regenerated viascripts/sync-plugin-mirrors.ts, never hand-edited),tests/hooks/counterparty-brief.test.ts. - Acceptance (red-first): the hook suite (spawn-based,
runHookpattern oftests/hooks/gap-loop.test.ts, temp vault, isolated HOME viahomeEnv) fails on the missing script; then passes: flag off emits byte-identical empty stdout; flag on with a qualifying prompt and a matched counterparty emits exactly onehookSpecificOutput.additionalContextenvelope with at most three dated items; a second run in the same session emits nothing (ledger); no real session id means no ledger write and no emission; flag on with an empty trigger list emits nothing; a prompt with no counterparty match emits nothing; the process ceiling holds (slow vault, exit 0, no output);tests/hooks/hooks-json-shape.test.ts,tests/core/install/adapters/grok-hook-parity.test.ts,tests/core/install/grok-hook-timeout.test.tsandtests/scripts/sync-plugin-mirrors.test.tsare all green after registration. - Depends on: B1, B2, A1 (dated-item supply for the acceptance fixtures).
B5: entity-read census compliance
- Files:
tests/core/brain/entities/entity-read-census.test.tsonly if the inventory needs the new reader named;src/core/brain/counterparty-brief.tsmust already useentityStatusInScope(B2). - Acceptance: the entity-read census suite passes (the new module reads entity records only through the one status predicate, or is added to the exclusion inventory with a reason);
tests/core/architecture/import-cycles.test.tsandtests/core/architecture/state-surface-census.test.tsstay green (the ledger file lives beside the existing injection-ledger state, same surface). - Depends on: B2, B4.
Lane C - whole-tree closure: census sweep, docs, CHANGELOG, version (runs last)
C1: whole-tree census and registry sweep
- Files: none expected (a verification task; fixes land in the owning lane's files if a census names one).
- Acceptance: with A and B complete, run and pass, in one
bun testinvocation:tests/mcp/brain-tools-parity.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-path-census.test.ts,tests/core/architecture/import-cycles.test.ts,tests/core/architecture/progress-census.test.ts,tests/core/architecture/append-shard-census.test.ts,tests/core/architecture/verdict-vocabulary-census.test.ts,tests/core/architecture/origin-channel-census.test.ts,tests/core/architecture/harness-identity-census.test.ts,tests/core/architecture/state-surface-census.test.ts,tests/core/brain/entities/entity-read-census.test.ts,tests/core/brain/sync-lockfile.test.ts,tests/mcp/agent-scope-matrix.test.ts,tests/mcp/visibility-matrix.test.ts,tests/hooks/hooks-json-shape.test.ts,tests/core/install/adapters/grok-hook-parity.test.ts,tests/scripts/sync-plugin-mirrors.test.ts,tests/core/brain/config-template-ratchet.test.ts- the recon A seventeen-entry checklist items 1-17 and the recon B hook parity list, all satisfied with named evidence. - Depends on: A5, A6, B3, B4, B5.
C2: docs and behavior disclosure
- Files:
docs/mcp.md(tool-table rows forbrain_pledgeandbrain_intake_pledges; thebrain_context_packentry names theentity_factsconditional option and the new tools' reach behavior, including the inherited second-hand-text limit; thebrain_briefentry names the pledges section),docs/cli-reference.md(thebrain todayoutput gains the pledges section),docs/updating.md(behavior-break disclosure for the conditional pack member, the dashboard totals extension and thebrain_brief view=todayshape change, pertests/docs/behaviour-break-disclosure.test.ts),README.mdonly if its feature list names the today sections. - Acceptance:
tests/docs/behaviour-break-disclosure.test.tspasses; every doc edit names features that exist in the diff (no aspirational rows). - Depends on: C1.
C3: CHANGELOG and version bump
- Files:
CHANGELOG.md(new## [1.91.0]heading with date, Added/Changed entries in house style, compare-link reference),package.json(1.90.0->1.91.0), version mirrors viabun run scripts/sync-version.ts. - Acceptance: the parity docblock history and the CHANGELOG agree on what the minor adds;
bun run scripts/sync-version.tsreports no drift; the link reference resolves. - Depends on: C2.
Commit sequencing
- A1 (contract first), then B1 in parallel.
- Lane A: A2 -> A3 -> A4 -> A5 -> A6. Lane B (after A1): B2 -> B3 -> B4 -> B5.
- Lane C: C1 -> C2 -> C3.
- Format (
./node_modules/.bin/oxfmt) and lint (oxlint) on changed files before every commit; the pre-commit hook runs them whole-tree.