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.
Temporal + synthesis - one timeline index, five projections, two new atoms
Status: draft Author: @claude-vps-agent (via feature-release-playbook) Audience: implementation
Problem statement
Open Second Brain has no first-class time axis. Preferences carry
scattered date scalars (created_at, confirmed_at,
last_evidence_at, retired_at, unconfirmed_until) and per-day
event logs land in Brain/log/<date>.jsonl, but no helper assembles
a chronological view: per preference, per topic, or per window.
Operators cannot ask "how did my position on X evolve", agents
cannot answer "what changed in the vault this week", and the
brain_doctor / brain_digest surfaces have no notion of staleness
or activity drift over time. Synthesis surfaces (daily / weekly
briefs) that the operator wants would, without a temporal layer,
degenerate into point-in-time counters - they could not show drift.
Scope
- New named subsystem
src/core/brain/temporal/(one per release, precedent: v0.10.17link-graph/). - Atoms (data-shape additions):
TemporalEvent- normalized chronological event drawn fromBrain/log/<date>.jsonl, retired/, and preference frontmatter. Flat shape withat: string(canonical UTC ISO),kind: BrainLogEventKind(reuses the existing event-kind enum), plus optional denormalized slots (prefId,topic,result,artifact,transitionFrom,transitionTo,reason,text,validFrom,validUntil,recordedAt,source).TimelineIndex- frozen materialized view of all events in a requested window, grouped by kind / pref_id / topic.- Bi-temporal frontmatter atoms (additive optionals on preference
- signal frontmatter):
valid_from,valid_until,recorded_at. Read-only this release; write paths can land in a future release without breaking compatibility.
- signal frontmatter):
- New
temporal:block in_brain.yaml(parallel tolink_graph:).
- Pure helpers (projections over
TimelineIndex):temporal/build-index.ts-buildTimelineIndex(vault, opts).temporal/select-events.ts-selectEvents(index, filters).temporal/belief-evolution.ts-buildBeliefEvolution(index, vault, target).temporal/stale-watch.ts-findStaleEntries(index, vault, cfg).temporal/daily-brief.ts-buildDailyBrief(index, vault, date).temporal/weekly-brief.ts-buildWeeklySynthesis(index, vault, weekEnd).
- Consumers (CLI + MCP):
- Five new full-scope MCP tools:
brain_timeline,brain_belief_evolution,brain_stale_scan,brain_daily_brief,brain_weekly_synthesis. - Five new CLI verbs:
o2b brain timeline,evolution,stale,daily,weekly.
- Five new full-scope MCP tools:
- Tests:
- Unit tests for every atom + helper under
tests/core/brain/temporal/. - MCP shape tests under
tests/mcp/. - CLI surface tests under
tests/cli/.
- Unit tests for every atom + helper under
Out of scope
- Writing the new bi-temporal frontmatter atoms (
valid_from/valid_until) - this release reads them where they exist; bulk-write tooling, dream-pass automatic timestamping, and migration scripts are deferred to a future release. - Temporal intent classifier (the "is this query temporal" regex
from gbrain a19ee8b): forbidden by project pref
language-agnostic-only. Operator invokes the temporal helpers explicitly through CLI / MCP, not through query-text sniffing. - LLM-driven synthesis prose. Helpers return deterministic data shapes; the agent does narrative work externally.
brain_searchintegration - timeline surfaces stay separate this release. (Future: afrom:/until:search modifier could use the same atom layer.)complexity-vs-activity ratio(t_03752ca6) - deferred; ties intosrc/core/discipline/rather thantemporal/. Leaving for a discipline-focused release.- Two-stage signal review gate (
t_ef94345e) - dream-pass change, unrelated to temporal axis.
Chosen approach
Variant 1 from variants.md: a single materialized TimelineIndex
plus pure projections. The atom layer adds three frontmatter slots
and one event type; the index builder scans Brain/log/*.jsonl,
Brain/retired/, and active preference frontmatter once per
invocation; five helpers project the index into operator-facing
shapes; five consumers (CLI verbs and MCP tools) expose the
helpers. The index is frozen and only ever built from disk in one
place, so every helper observes the same window semantics, the
same retirement treatment, and the same source-pointer
resolution.
Window semantics are inclusive at since and exclusive at until
([since, until)), expressed as ISO-8601 UTC timestamps. Days are
expressed via the existing validateIsoDate helper. Weekly windows
default to ISO-8601 week boundaries (Monday 00:00:00 UTC -
following Monday 00:00:00 UTC), configurable via the
temporal.weekly_start_dow slot which takes ISO-8601 weekday
numbers (1=Monday ... 7=Sunday) - no language hardcoding.
Belief-evolution follows topic-renames across slugs by chaining
supersedes / superseded_by links on retired entries. The
chain-walker is bounded by the count of retired entries (no
infinite recursion even on a malformed chain).
Stale-watch reads three thresholds from config
(temporal.stale_pref_days, temporal.stale_signal_days,
temporal.stale_log_days), defaulted to 90 / 30 / 180 days
respectively. Pure structural staleness based on the most-recent
event-time stamp per entry; nothing about content.
Daily-brief returns event counts grouped by BrainLogEventKind,
the set of preferences whose status transitioned in the window
(derived from promote / retire / force-confirmed / reject
events), the vault delta (new feedback signals / new retired /
applied / violated counts) versus the previous day, and the list
of source-pointers cited. Weekly-synthesis returns the same shape
over a 7-day window plus contradiction counts (combining
signal-suppressed events with apply-evidence events where the
payload result is "violated") and a "retired in window" list.
Design decisions
- One materialized index, five projections. Sharing data, not
operations, eliminates window-semantics drift and matches the
v0.10.17
link-graph/precedent. - Atoms are additive optionals.
BrainPreference,BrainSignal, andBrainRetiredRecordfrontmatter readers grow optionalvalid_from/valid_until/recorded_atslots; existing files stay byte-identical when not opted in. - Index builder is the single disk-touching helper. The five projection helpers are pure functions over the frozen index, trivially testable with synthetic fixtures.
- ISO-8601 everywhere. All timestamps in
TimelineIndexare canonical UTC strings of the shapeYYYY-MM-DDTHH:MM:SSZ(or.SSSZwhen source data carries sub-second precision), matchinglog-jsonl.ts'sISO_UTC_TS_RE. Window inputs accept either an ISO date (interpreted asT00:00:00Z) or a full ISO timestamp. - Weekly weekday number is configured, not detected. No English-word detection like "Monday"; the slot takes 1-7 per ISO-8601, defaulted to 1 (Monday).
sinceinclusive,untilexclusive. Mirrors the existing digest convention indigest.ts(window: {since, until}).- Briefs do NOT call the LLM. They are deterministic counters
- status-transition lists + source-pointer arrays. Operator-side agents do the narrative work over the structured payload.
- MCP tools register in full scope only. Writer scope stays
frozen at four tools. Five new tools land alongside
brain_unlinked_mentions/brain_concept_synthesis/brain_moc_auditin the full scope. Tool-count assertion intests/mcp/mcp.test.tsupdates from 26 to 31. - CLI verbs follow
o2b brain <verb>convention. Each verb reuses the existing--vault/--jsonflags via the shared CLI helpers.
File changes
New files
src/core/brain/temporal/types.ts # TemporalEvent + TimelineIndex + config defaults
src/core/brain/temporal/build-index.ts # buildTimelineIndex(vault, opts)
src/core/brain/temporal/select-events.ts # selectEvents(index, filters)
src/core/brain/temporal/belief-evolution.ts # buildBeliefEvolution(index, vault, target)
src/core/brain/temporal/stale-watch.ts # findStaleEntries(index, vault, cfg)
src/core/brain/temporal/daily-brief.ts # buildDailyBrief(index, vault, date)
src/core/brain/temporal/weekly-brief.ts # buildWeeklySynthesis(index, vault, weekEnd)
src/cli/brain/verbs/temporal-timeline.ts # o2b brain timeline
src/cli/brain/verbs/temporal-evolution.ts # o2b brain evolution
src/cli/brain/verbs/temporal-stale.ts # o2b brain stale
src/cli/brain/verbs/temporal-daily.ts # o2b brain daily
src/cli/brain/verbs/temporal-weekly.ts # o2b brain weekly
tests/core/brain/temporal/build-index.test.ts
tests/core/brain/temporal/select-events.test.ts
tests/core/brain/temporal/belief-evolution.test.ts
tests/core/brain/temporal/stale-watch.test.ts
tests/core/brain/temporal/daily-brief.test.ts
tests/core/brain/temporal/weekly-brief.test.ts
tests/core/brain/temporal/bi-temporal-atoms.test.ts
tests/mcp/temporal-mcp-tools.test.ts
tests/cli/brain-temporal-cli.test.ts
Modified files
src/core/brain/policy.ts # BRAIN_TEMPORAL_DEFAULTS + resolveTemporal() + temporal: validator
src/core/brain/types.ts # BrainTemporalConfig + ResolvedBrainTemporalConfig + BrainConfig.temporal?
src/core/brain/preference.ts # read optional valid_from/valid_until/recorded_at
src/core/brain/signal.ts # read optional valid_from/valid_until/recorded_at
src/core/brain/dream.ts # RetiredRecord: optional valid_from/valid_until/recorded_at
src/mcp/brain-tools.ts # five new tool registrations
src/cli/brain.ts # dispatch five new verbs
src/cli/brain/verbs/index.ts # register five new verbs
src/cli/brain/help-text.ts # help block for five new verbs
tests/mcp/mcp.test.ts # 26 -> 31 tool inventory assertion
Approximate file count: 17 new (helpers + verbs) + 9 new tests + 9 modified = ~35-40 source files plus the brainstorm + design + plan + cli-output set (3 + cli-output) brings the PR to ~45-55 files. README + CHANGELOG + version manifests add another ~10 during phases 5-6.
Risks and open questions
- Index width. If the materialized event shape needs a new
field mid-implementation (e.g. evidence-violated needs a
contradiction-target slot), the atom is widened in
types.tsand every helper rebuilds. Mitigation: settle theTemporalEventfield list during phase 0 step 7 (now) and resist creep; future fields can land as additive optionals exactly like backlink atoms in v0.10.17. - Retired-chain cycles. Bad
supersedes/superseded_bylinks could loop. Mitigation: chain-walker carries a visited set; break with a warning emit, never throw. - Weekly boundary on DST / timezone vaults. All math is in UTC.
Operators in non-UTC timezones see weeks that don't align with
their local calendar. Acceptable for v0.10.18 - the brief shape
already includes the literal ISO timestamps; downstream agents
can re-window locally. Future release can add a
temporal.timezoneslot if operator demand exists. - Empty vault. All projection helpers must return frozen empty envelopes (not throw) when the timeline has zero events in the window. Covered in tests.
- Sub-second timestamps in JSONL vs second-precision in retired/. The index normalizes both to the canonical UTC shape before grouping; collisions on the same second are resolved by source-pointer order (deterministic).