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

Dated commitments, capture to surface - pledge pages with evidence, then a counterparty brief and entity facts

Status: implemented (shipped in 1.91.0) Author: release orchestrator (via feature-release-playbook) Audience: implementation Cards: t_da8673aa (dated-item supply), t_43b0a379 (delivery)

Problem statement

A one-off promise made in prose is invisible to Open Second Brain today. Open loops are manual @osb loop markers with no due date and no store, and the only due-dated pages are cadence-driven recurring obligations, so nothing answers "what did I promise, to whom, by when". At the moment of need - a conversation with the person the promise was made to - nothing injects the relevant dated facts either: context packs are tier-then-recency with no notion of "who is this about", and no hook conditions on a counterparty.

Premise verdicts (verified against the live tree, this session)

The card claims were checked against the source before any design choice. Verdicts below are load-bearing; every verdict marked "verified here" was re-opened in the worktree during this phase, and each stands on the in-tree file:line it cites.

  1. "Open loops have no due dates" (t_da8673aa) - partially refuted, corrected. Recurring obligations are first-class due-dated pages with pure UTC calendar math (src/core/brain/obligations.ts: ObligationPage, nextDueDate, overdue flag, daysUntilDue, due-sorted list). What is genuinely absent is a ONE-OFF, prose-extracted, evidence-cited page family. The feature adds a family; it does not touch the loop markers.
  2. "The belief commitment tier already exists" (naming hazard) - verified here. src/core/brain/preference.ts:213-218 declares commitment?: BrainCommitmentTier (exploring | leaning | decided | locked), validated by src/core/brain/commitment.ts, applied to preferences, theses and decisions. The bare commitment: frontmatter key is taken on three page families. The new family is named pledges and never uses that key.
  3. "Mirror the brain_agenda events contract" (t_da8673aa) - verified with correction. brain_agenda (src/mcp/brain/calendar-tools.ts:271-309) is stateless analysis over caller-supplied events: it contributes the transport shape (agent posts typed objects, kernel validates arrays, additionalProperties: false), nothing else. The write-side semantics - validate the whole payload before any write, idempotent commit, provenance, trust derived from cited sources - come from the extraction-intake precedent (src/core/brain/intake/extract-intake.ts, src/mcp/brain/ner-tools.ts).
  4. "Projection into facts and entity edges" (t_da8673aa) - verified as feasible with one line of vocabulary. DEFAULT_RELATION_TYPES (src/core/graph/relation-vocab.ts:37-44) is data-driven; a frontmatter field whose name is a known relation becomes typed edges through src/core/graph/frontmatter-relations.ts, ingested by the search indexer (src/core/search/indexer.ts:666) and the link graph. Search admission of a new Brain/pledges/ directory is automatic (index admission defaults to admit). The derived-fact and claim-graph readings of "facts" are rejected as duplication with census drag and no card requirement (see design decisions).
  5. "Inject at session start" (t_43b0a379) - refuted as stated, corrected in design. The SessionStart payload carries no prompt text (hooks/recall-inject.ts:358 reads payload.prompt, which exists only on UserPromptSubmit), and both the counterparty and the intent must be derived from the prompt deterministically. UserPromptSubmit is an allowed additionalContext carrier (hooks/lib/context-events.ts:26). The brief therefore rides UserPromptSubmit with once-per-session ledger suppression: the first qualifying turn of a session emits it, which realizes the card's intent ("before you start") without inventing a signal SessionStart does not carry.
  6. "Reply or meeting intent" (t_43b0a379) - verified as a discipline hazard. Hardcoded natural-language word lists are a standing refusal in this repository (src/core/brain/entities/status-scope.ts:14-17, src/core/graph/visibility.ts:5-8, src/mcp/brain/ner-tools.ts:11-13). The design uses an operator-declared trigger vocabulary in machine-local config; nothing ships an English verb list.
  7. "An upcoming calendar meeting" as a brief item (t_43b0a379) - refuted for this wave. There is no calendar store: brain_agenda analyzes caller-supplied events only. The brief draws its dated items from the pledge family and preference facts.
  8. "Only shareable items; private pages excluded" (t_43b0a379) - verified machinery exists, adopted. The reserved visibility token private dominates any co-tag (src/core/graph/visibility.ts:93), strictestVisibilityOf computes the intersection for derived items, per-path verdicts fail closed, and owner-scope views enforce identical-to-absent. The brief and the pack section both route through these.
  9. "t_da8673aa unblocks t_43b0a379; the pull side is dependency-free" (validator comments) - verified here. Open loops carry no date (src/core/brain/open-loops.ts:44-49), so the push side has no dated supply until the pledge family exists; the pull-side section reads only candidates the pack already kept and ships independently.

No card is refuted outright; both are built under the corrections recorded above.

Scope

  • A one-off pledge page family at Brain/pledges/<slug>.md: title, promise text, due date, source page, evidence quotes verified against the source, counterparty entity links, fulfilled stamp; add/fulfill/show/list/remove with due-sorted listing, overdue flag and days-until-due; remove archives the page.
  • An agent-executed extraction intake (brain_intake_pledges): the agent posts typed pledge extractions (title, due, evidence quotes, source, optional counterparty names); the kernel validates everything before any write, commits idempotently, anchors counterparties server-side through the canonical entity registry, and reports unanchored names. The kernel never calls a model.
  • A direct CRUD surface (brain_pledge) mirroring brain_obligation's operation shape.
  • Projection: one new relation token promised_to in the relation vocabulary; the pledge frontmatter becomes typed pledge-to-entity edges through the existing frontmatter-relations ingest. No new projection code.
  • A pledges section on the today dashboard beside obligations and open loops.
  • A pull-side entity_facts section as a conditional option on brain_context_pack (config key entity_facts_context_pack, default off): entities anchored from the pack query, facts drawn only from candidates the pack already kept, conditional report member and output projection so default packs stay byte-identical.
  • A push-side opt-in counterparty brief hook on UserPromptSubmit: off by default (machine-local flag plus env override), fires only on a confident single counterparty match AND an operator-declared trigger token, emits at most three dated shareable items with source pages, at most once per session via the injection ledger, fail-open under the shared process ceiling.
  • Census and registry registrations for all of the above, docs, CHANGELOG entry and the minor version bump inside the PR.

Out of scope

  • Any change to the @osb loop marker machinery or its delete-marker-closes-loop semantics.
  • A CLI verb for pledges (the MCP tools, the dashboard section and the hook cover both cards; a verb would add registration drag without a card requirement).
  • Gmail/Calendar/Contacts ingestion; any calendar store (there is none; brain_agenda is caller-supplied-events analysis).
  • Derived-fact or claim-graph projection of pledges.
  • Intent detection beyond the operator-declared trigger vocabulary, and doctor surfacing of the flag-on-empty-vocabulary state (documented in the hooks README instead).
  • A dedicated entity_facts MCP tool (the conditional option on the existing pack tool avoids the tool census entirely).
  • SessionStart injection of the brief (refuted mechanically; see premise verdict 5).

Chosen approach

Variant 1 of the consultant set (sibling page family copied from the obligations precedent, frontmatter-relation projection, one shared privacy/cap kernel for both delivery surfaces, conditional pack option, opt-in hook), with three documented deviations: the family is named pledges (not promises) so the typed error PledgeError cannot be confused with the language's Promise and the operator-facing word stays distinct from both "obligation" and the "commitment" tier; the surface is two tools (brain_pledge CRUD, brain_intake_pledges intake) rather than one tool with an intake operation, because additionalProperties: false schemas cannot express per-operation payloads cleanly and each tool then mirrors an exactly-reviewed precedent; and one new relation token (promised_to) rather than two.

The substrate lane lands the page family, intake and projection. The delivery lane lands the pack section and the hook against the substrate's pure modules only. Both lanes commit their shared pure modules before anything that consumes them; the pinned contract in plan.md fixes the exact names.

Design decisions

  • Family name and frontmatter keys. Brain/pledges/<slug>.md; bare keys in the obligations idiom (title, created_at, due, source, evidence, promised_to, fulfilled, agent). The key commitment: keeps meaning the epistemic tier; no pledge key or tool wording uses the word "commitment" for the page family.
  • Evidence quotes are verified at write time. Every quote must occur in the cited source page (containment through the shared quote-span comparators, src/core/brain/distill/quote-spans.ts), otherwise the write refuses with a named validation error. There is no unverified-evidence lane and no new verdict vocabulary, so a stored quote is one the source contained when the pledge was written. The source page must exist and be readable at the caller's reach; a pledge citing nothing is refused.
  • Projection through the relation vocabulary, not a second store. promised_to joins DEFAULT_RELATION_TYPES; the pledge page's promised_to: frontmatter carries anchored entity ids and the existing frontmatter-relations ingest emits the typed edges. That membership is the whole vocabulary, though: DEFAULT_RELATION_TYPES doubles as the recognised preference relation-field set, so adding promised_to also made it a preference relation field, and src/core/brain/preference.ts:1188-1198 carries an explicit promised_to exclusion to keep pledge edges out of preference pages - consumers derived from the vocabulary pick up every new token, so each addition needs its exclusions checked. Fact surfacing is the page itself: search admission is automatic, the dashboard section and the delivery surfaces read the family directly. Projecting pledges into derived-fact preferences would duplicate every promise into a second mutable artifact and multiply the census surface for no card requirement.
  • Intake is validate-before-write, idempotent, kernel-anchored. Identity is a content hash over the normalized (title, due, source) triple: a repeat with the same payload is a reported no-op, the same identity with a different payload is a named mismatch error (the preference idempotency-key precedent). Storage is keyed on the title slug (slugify(title), pledge-intake.ts:319), so two pledges that share a title cannot both exist: the 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 (at most 100 pledges per intake, 32 counterparty names per pledge, 200 characters per name; MAX_INTAKE_PLEDGES / MAX_INTAKE_COUNTERPARTIES / MAX_INTAKE_COUNTERPARTY_NAME_LENGTH), and a batch over a cap refuses whole. Counterparty names are anchored server-side against canonical-scope entities through the shared anchoring kernel (anchorEntityForms + entityStatusInScope); the kernel never trusts caller-supplied entity ids. Names that anchor nowhere are reported on the result and stored nowhere - a pledge exists without edges rather than with fake ones; re-posting the same payload after the entity is registered adds the edge (the re-anchor arm). A stored edge the readable canonical registry can no longer reproduce is reported under staleEdges and the page is left byte-identical, never edited: 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.
  • The brief rides UserPromptSubmit, once per session. Counterparty and intent are derived from the prompt: exactly one canonical-scope entity must match by name or alias through the anchoring kernel (zero or multiple matches abstain), and at least one operator-declared trigger token must occur in the prompt (normalized token containment - the tokens are the operator's, in the operator's language). The injection ledger suppresses repeats for the session; no real session id means no ledger write and no emission.
  • Brief items are shareable-only, dated, capped. Items come from open pledges promised to the matched entity (due-sorted) and recent non-private preference pages whose bodies anchor the entity (bounded walk with a page-read cap and a character budget, the morning-brief discipline). Not every item is dated: a preference page carries the date it was created, and a preference with no calendar date is an undated item that sorts last and renders undated (counterparty-brief.ts:127, :394-395, :481) - the "dated" in the design's name is the pledge supply leading, not a guarantee about preference items. The read cap is a WINDOW, not a filter applied afterwards: both walks read at most their cap of pages in the vault's stable (code-unit) name order BEFORE the recency/due sort, so past the cap the globally newest preferences or the soonest-due pledges can fall outside the window. The preference walk reads at most BRIEF_PAGE_READ_CAP = 24 pages; the pledge walk has TWO ceilings - it keeps at most BRIEF_PLEDGE_READ_CAP = 24 pages and parses at most BRIEF_PLEDGE_SCAN_CAP = 96, the completed promises it drops included - so its filesystem work cannot grow with the size of Brain/pledges/. A page whose visibility carries the reserved token is excluded regardless of reach, because a hook-injected block leaves the machine; an item derived from several sources inherits strictestVisibilityOf; withheld items are dropped silently (identical-to-absent - nothing counts them). The second-hand-text limit already disclosed for brain_context_pack (a readable page may name a private page) is inherited and disclosed the same way, not claimed closed.
  • entity_facts is a conditional option on the existing pack tool. Config key entity_facts_context_pack resolved at the tool seam exactly like density_ranking_context_pack; a conditional ContextPackOptions.entityFacts boolean; a conditional report member listing per anchored entity (canonical scope, cap 3) the ids of kept candidates whose bodies anchor it. No new reads, no new tool, no change to the other three packContext callers when off; entity pages that fail the caller's view are treated as absent, so a private entity never surfaces its rollup; at remote reach the section respects the same view the items do.
  • Intent config surface. counterparty_brief_enabled (machine-local main config boolean with env override OPEN_SECOND_BRAIN_COUNTERPARTY_BRIEF_ENABLED, the gap-loop resolver pattern) and counterparty_brief_triggers (machine-local list). Flag off is an immediate no-op keeping stdout byte-identical; flag on with an empty trigger list is inert and the requirement is documented in the hooks README (doctor surfacing is out of scope).
  • Registration drag is paid where it is caused. Two new tools: frozen parity docblock plus pin, two visibility-surface-registry rows, the two-directional visibility census sweep, probe-catalogue recipes and agent-scope matrix classification, vault-path-safe responses. The archive move: write-site and destructive-site entries plus their pinned-count docblock history. The hook: hooks.json row in the exact command shape, codex mirror via the sync script, grok parity registration, README table row. Lane C re-runs every census whole-tree.

File changes

New: src/core/brain/pledges.ts, src/core/brain/pledge-intake.ts, src/core/brain/counterparty-brief.ts, src/mcp/brain/pledge-tools.ts, hooks/counterparty-brief.ts, plus their test suites (tests/core/brain/pledges.test.ts, tests/core/brain/pledge-intake.test.ts, tests/core/brain/counterparty-brief.test.ts, tests/core/brain/context-pack-entity-facts.test.ts, tests/mcp/pledge-tools.test.ts, tests/mcp/pledge-reach.test.ts, tests/hooks/counterparty-brief.test.ts).

Modified: src/core/brain/path-constants.ts, src/core/brain/paths.ts, src/core/graph/relation-vocab.ts, src/core/brain/today-dashboard.ts, src/mcp/brain/brief-tools.ts (the brain_brief view=today projection embeds the whole dashboard), src/mcp/brain-tools.ts, src/core/search/visibility-surface-registry.ts, src/core/brain/destructive-sites.ts, src/core/config.ts, src/core/brain/context-pack.ts, src/mcp/brain/pack-tools.ts, hooks/hooks.json, hooks/README.md, hooks/lib/injection-ledger.ts, src/core/install/grok-asset.ts, plugins/codex/hooks/hooks.json (via the sync script), the touched census and parity tests, docs/mcp.md, docs/cli-reference.md, docs/updating.md, CHANGELOG.md, package.json plus the version mirrors via scripts/sync-version.ts.

Rough total stays inside the 50-70 changed-file budget.

Risks and open questions

  • Naming bleed. Even with the family named pledges, prose in tool descriptions must not say "commitment" for the page family; the parity and census docblocks pin the wording reviewers read first.
  • Anchoring false positives. A brief that fires on a weak match injects the wrong person's facts. The mitigations are the kernel's own quality gate (minimum form length, clean leading edge), canonical scope only, and the exactly-one-match abstention; anything weaker abstains.
  • Hook latency. Five hooks already run per event under a 10-second host timeout and an 8-second self-ceiling. The brief hook checks the flag first, bounds its walk with a page-read cap and a character budget, and arms the shared process ceiling; the anchoring pass reads only canonical-scope entity forms once per prompt.
  • Privacy residue. The known, disclosed limit is second-hand text: a readable page may name a private page, and no per-page gate can rewrite prose. The registry row for the new tools and the docs say so plainly instead of claiming airtightness.
  • Census equality pins. Every pinned-count docblock (write-site, destructive-site, visibility census history) must be edited in the same commit as the entry that bumps it; forgetting one fails CI with a named file, so Lane C re-runs the censuses whole-tree before the docs commit.
  • Open question for implementation: the exact quote-containment normalization reuses normalizeForQuoteComparison/spanOccursIn; if a legitimate quote fails containment because the source formats dates differently, the refusal names the mismatch and the agent re-quotes verbatim - no leniency knob ships.