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
Temporal + synthesis - implementation plan
Order matters - the materialized-index variant has a strict layered
DAG (atoms - index - projections - consumers). Each task lands on
feat/temporal-synthesis as a separate conventional commit on top
of the brainstorm commit.
Tasks
Task 1: Temporal atoms + config block
- Files:
src/core/brain/temporal/types.ts(new),src/core/brain/types.ts(modified - addBrainTemporalConfig+ResolvedBrainTemporalConfig+BrainConfig.temporal?),src/core/brain/policy.ts(modified - addBRAIN_TEMPORAL_DEFAULTS,resolveTemporal(cfg),temporal:validator with safe-integer / range checks),tests/core/brain/temporal/bi-temporal-atoms.test.ts(new). - Acceptance:
TemporalEventis a flat shape withat: string(canonical UTC ISO),kind: BrainLogEventKind(reuses existing enum values verbatim),source: TemporalEventSource(vault-relative log path + line number when known), plus optional denormalized slots:prefId,topic,result,artifact,transitionFrom,transitionTo,reason,text,validFrom,validUntil,recordedAt. Frozen viaObject.freeze.TimelineIndexis a frozen{events, eventsByKind, eventsByPrefId, eventsByTopic, window}shape.BRAIN_TEMPORAL_DEFAULTSexposesstale_pref_days: 90,stale_signal_days: 30,stale_log_days: 180,weekly_start_dow: 1,daily_window_offset_hours: 0.resolveTemporal(cfg)returns a fully-populated config; absent block falls back to defaults.- Validator rejects: non-positive integers, weekly_start_dow outside [1, 7], offset_hours outside [-23, 23].
- Test covers happy-path config, defaults fallback, and each validator branch.
- Depends on: none.
Task 2: TimelineIndex builder
- Files:
src/core/brain/temporal/build-index.ts(new),tests/core/brain/temporal/build-index.test.ts(new). - Acceptance:
buildTimelineIndex(vault, opts)walksBrain/log/<date>.jsonlvia existingreadLogDayfor every date file in the window, plusBrain/retired/*.mdvia existingreadAllRetiredshape, plus active preference frontmatter via existingreadPreferenceshape, and returns a frozenTimelineIndex.- Window inputs:
since?(ISO date or full ISO timestamp),until?(ISO date or full ISO timestamp). Defaultsinceis epoch; defaultuntilis now + 1ms (exclusive). - All event timestamps normalized to canonical UTC string before grouping. Sub-second precision preserved when present.
- Tie-breaker for equal timestamps: source-pointer order (so the result is deterministic).
- Test: synthetic vault with three JSONL files + two retired entries + four active prefs; assert events list, kind groups, pref groups, topic groups, and frozen-ness.
- Empty vault: returns frozen index with zero events and empty groups (no throw).
- Depends on: Task 1.
Task 3: Select-events projection + bi-temporal frontmatter reader
- Files:
src/core/brain/temporal/select-events.ts(new),src/core/brain/preference.ts(modified - additivevalid_from?,valid_until?,recorded_at?optional reads on the existing frontmatter reader),src/core/brain/signal.ts(modified - same three optional slots),src/core/brain/dream.ts(modified -RetiredRecordgains three optional slots),tests/core/brain/temporal/select-events.test.ts(new). - Acceptance:
selectEvents(index, filters)accepts{pref_id?, topic?, kind?, since?, until?}and returns a frozenReadonlyArray<TemporalEvent>filtered by the AND of every set predicate.- When no filter is set, returns the index's full events array (still frozen, same reference is fine).
- Bi-temporal atom reads: existing files without the new keys
parse as before (no schema break); files with
valid_fromset surface it onTemporalEvent.validFrom; same forvalid_untilandrecorded_at. - Test: every filter combination across a 6-event synthetic fixture; empty-filter happy path; bi-temporal atom presence / absence smoke.
- Depends on: Task 2.
Task 4: Belief-evolution helper
- Files:
src/core/brain/temporal/belief-evolution.ts(new),tests/core/brain/temporal/belief-evolution.test.ts(new). - Acceptance:
buildBeliefEvolution(index, vault, target)acceptstarget: {prefId: string} | {topic: string}and returns a frozen{target, transitions, evidence, retirements, generatedAt}envelope.transitionsis the chronological list of status changes (unconfirmed -> confirmed -> quarantine -> retired, intermediate states emitted), each entry carriesat,from,to, and the originating event reference.evidenceis the chronological list of applied / violated / outdated events with a per-phase running count.retirementscovers the retired entry plus the chain ofsupersedes/superseded_bylinks, with a visited-set cycle guard.- Empty target (no events found): returns the envelope with empty arrays, no throw.
- Test: synthetic 4-transition history (unconfirmed -> confirmed
-> quarantine -> retired) with three evidence events and a
cross-slug rename chain via
supersedes.
- Depends on: Task 3.
Task 5: Stale-watch helper
- Files:
src/core/brain/temporal/stale-watch.ts(new),tests/core/brain/temporal/stale-watch.test.ts(new). - Acceptance:
findStaleEntries(index, vault, cfg)returns a frozen{stalePreferences, staleSignals, staleLogFiles, thresholds, generatedAt}envelope.- Threshold logic: an entry is stale when the difference between
nowand the most-recent relevant event timestamp exceeds the threshold-days config value. - Per-kind thresholds applied independently
(
stale_pref_days,stale_signal_days,stale_log_days). - Test: synthetic vault with one stale pref, one fresh pref, one stale signal, one stale log file, asserting the envelope classification.
- Depends on: Task 2.
Task 6: Daily-brief helper
- Files:
src/core/brain/temporal/daily-brief.ts(new),tests/core/brain/temporal/daily-brief.test.ts(new). - Acceptance:
buildDailyBrief(index, vault, date)returns frozen{date, eventsByKind, statusTransitions, vaultDelta, sourcePointers, generatedAt}envelope.eventsByKindkeyed byBrainLogEventKind, with stable key order (sorted lexicographically).statusTransitionsis the list of pref-id status changes within the day.vaultDeltareportsnewPromotions(count ofpromoteevents),newRetired(count ofretireevents),newFeedback(count offeedbackevents),evidenceAppliedandevidenceViolated(count ofapply-evidenceevents with the matching payloadresult) as integers.sourcePointersis the deduplicated list of artifact wikilinks cited by evidence events in the day.- Test: synthetic day with 1 promotion + 2 applied + 1 violated
- 1 retired; assert each envelope slot.
- Depends on: Task 2.
Task 7: Weekly-synthesis helper
- Files:
src/core/brain/temporal/weekly-brief.ts(new),tests/core/brain/temporal/weekly-brief.test.ts(new). - Acceptance:
buildWeeklySynthesis(index, vault, weekEnd, cfg)returns frozen{windowStart, windowEnd, eventsByKind, statusTransitions, retired, contradictions, vaultDelta, generatedAt}envelope.- Window is computed from
weekEnd(ISO date) back to theweekly_start_dow-aligned Monday-or-other-weekday by config. contradictionscountssignal-suppressedandevidence-violatedevents grouped by pref_id.retiredlists every pref retired within the window with the retirement reason.- Test: synthetic 7-day window with 1 retirement, 2 contradictions, 4 transitions; assert envelope and window bounds.
- Depends on: Task 2.
Task 8: Five MCP tools
- Files:
src/mcp/brain-tools.ts(modified - registerbrain_timeline,brain_belief_evolution,brain_stale_scan,brain_daily_brief,brain_weekly_synthesisin full scope),tests/mcp/temporal-mcp-tools.test.ts(new),tests/mcp/mcp.test.ts(modified - tool inventory 26 -> 31). - Acceptance:
- Each new tool: schema-validates input (strict booleans /
string-tolerant integer coercion matching v0.10.17 precedent),
converts internal errors to MCP
INVALID_PARAMSwhere appropriate, returns a frozen envelope serialised as JSON. - Writer scope stays at 4 tools (unchanged).
tests/mcp/mcp.test.tstool-inventory assertion updated to 31- the five names added to the expected Set.
- Test for each tool: happy-path input + one INVALID_PARAMS case (bad type / out-of-range integer / unknown filter key).
- Each new tool: schema-validates input (strict booleans /
string-tolerant integer coercion matching v0.10.17 precedent),
converts internal errors to MCP
- Depends on: Tasks 4-7.
Task 9: Five CLI verbs
- Files:
src/cli/brain/verbs/temporal-timeline.ts(new),src/cli/brain/verbs/temporal-evolution.ts(new),src/cli/brain/verbs/temporal-stale.ts(new),src/cli/brain/verbs/temporal-daily.ts(new),src/cli/brain/verbs/temporal-weekly.ts(new),src/cli/brain.ts(modified - dispatch the five verbs),src/cli/brain/verbs/index.ts(modified - re-export),src/cli/brain/help-text.ts(modified - help block),tests/cli/brain-temporal-cli.test.ts(new). - Acceptance:
- Each verb supports
--vault,--json, plus verb-specific flags:timeline---pref-id,--topic,--kind,--since,--until,--limit.evolution---pref-idor--topic(mutually exclusive).stale- no extra flags; reads thresholds from config.daily---date(ISO date, default today UTC).weekly---week-end(ISO date, default today UTC).
- Invalid flag combos surface as
CliErrorwith the project-standard message shape. --jsonreturns the helper envelope; the default human-readable rendering is a short multi-line text block.- Test: each verb's argv parsing happy-path + one invalid-args case.
- Each verb supports
- Depends on: Task 8.
Out of scope reminders (do not implement here)
- Writing the bi-temporal frontmatter atoms back onto disk.
- LLM-driven brief narrative generation.
- Temporal intent classifier on
brain_search/brain_query. - Vault complexity-vs-activity ratio.
- Two-stage signal review gate.
Verification commands
bun test tests/core/brain/temporal/- subsystem unit tests.bun test tests/mcp/- MCP shape + inventory tests.bun test tests/cli/- CLI surface tests.bun test- full regression suite.bun run typecheck- strict TypeScript.bun run sync-version:check- manifests in lockstep (phase 6).