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

You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.

Task

A cluster of four related kanban tasks shipping as one release for the Open Second Brain project (Bun + TypeScript CLI o2b, Markdown vault, brain memory subsystem, MCP server).

Task A (t_5f65c992) - Sectioned read-only today dashboard

A read-only, multi-section "today" overview generated by the brain - distinct from the existing morning-brief by being domain-sectioned (due/overdue obligations, open loops, recent activity, totals) where each section is an independent live query over vault notes, never stored content. The dashboard re-derives every section on demand so it is maintenance-free.

Task B (t_4adb0b8b) - Typed, age-labeled recent-activity timeline

At session start, format recalled/loaded memories as a scannable chronological "Recent Activity" timeline: each entry prefixed with a type tag and a relative-age label ("2h ago", "1d ago"). NOTE: the section-grouped typed bullets with age labels ALREADY shipped (morning-brief.ts timelineBullet + relativeAge). The remaining gap is a genuinely chronologically MERGED timeline across event kinds, rendered from the existing TimelineIndex (buildTimelineIndex sorts all BrainLogEventKind events chronologically already, but nothing renders it as a human timeline or wires it into a session-start/dashboard surface).

Task C (t_97373418) - Open-loops carry-forward from prose markers

Scan prior-period daily notes / narrative prose for lightweight inline open-loop markers and surface those unfinished items in today's brief until explicitly closed. Lighter-weight than a recurring obligation - captures intentions noted in passing. Closing convention needs definition. Must be language-agnostic: the marker is a structural token, not a natural-language word list.

Task D (t_d7be2a0c) - Prose markers into logged frontmatter mutations

Parse imperative completion/update markers the operator jots into daily prose, resolve them to the referenced notes, and apply property mutations - logging each change. Must be deterministic and logged (one log event per applied mutation); ambiguous note references surface as a conflict rather than guess.

Project context

Open Second Brain, TypeScript on Bun, strict typecheck + oxlint, 5687 tests. Current version 1.30.1.

Recent commits: 13bde6c3 refactor: remove all import cycles, decompose search.ts (v1.30.1) (#137) fd5661f9 feat: governance visibility - vitals scorecard + batch-inflation lint (v1.30.0) (#136) a99b0e71 feat(brain): add o2b brain vitals scorecard + batch-concept-inflation lint (#135) 70fb36e1 feat: operability, safety & first-run experience (v1.29.0) (#134) ac26a675 feat: retrieval & ranking quality (v1.28.0) (#133)

Related files (verified current-state anchors):

  • src/core/brain/morning-brief.ts: buildMorningBrief (section-grouped typed bullets, timelineBullet:157, scanRecentLog:108 reads reconcile open questions + notes from Brain log)
  • src/core/brain/time.ts:44 relativeAge ("Nm/Nh/Nd/Nw/Nmo/Ny ago", clock-injectable)
  • src/core/brain/temporal/build-index.ts:66 buildTimelineIndex (the ONE chronological merge primitive: sorts all BrainLogEventKind events by timestamp); select-events.ts:30 selectEvents(since/until)
  • src/core/brain/obligations.ts:311 listObligations (already computes overdue + daysUntilDue, sorted); Brain/obligations/*.md file-per-item store
  • src/core/brain/inline.ts: existing @osb marker grammar - MarkerKind = "feedback" ONLY (KNOWN_KINDS:35), parseInlineMarker:82 (@osb feedback positive topic=... principle=...), parseBlockMarker:221 (```osb fenced), discoverMarkersDetailed:322 (fence-aware, skips consumed @osb-checked sentinels), inline-rewrite.ts rewriteMarkers:47 (atomic idempotency annotation, lockfile-protected)
  • src/cli/brain/verbs/*: 118 verb files; flat switch dispatch in src/cli/brain.ts; scanInline verb walks notes.read_paths config (vault daily notes are user-owned, found via config, NOT a hardcoded Daily/ path)
  • src/core/brain/session-lifecycle.ts:453 captureMarkers -> emitSignal -> Brain/inbox/sig-*.md (feedback-only downstream)
  • src/core/brain/attributes.ts:129 assignNoteAttribute (schema-pack-validated, fail-closed AttributeVocabularyError listing declared fields, atomic frontmatter write); CLI-only today, no MCP wrapper
  • src/core/brain/notes/note-path.ts:22 resolveNotePath (exact vault-relative path only; NO title->path resolver exists anywhere)
  • src/core/brain/log.ts:259 appendLogEvent (canonical audit primitive, 19 callers, typed BRAIN_LOG_EVENT_KIND)
  • src/core/brain/policy.ts:119 BRAIN_GUARDRAIL_DEFAULTS + loadGuardrailsConfigSafe (opt-in capability flags in Brain/_brain.yaml guardrails block; derive-tools.ts:29 shows the gating idiom)
  • src/mcp/brain/brief-tools.ts:372 brain_brief view=morning|daily|weekly|monthly|operator|digest via dispatchByView table (src/mcp/brain/shared.ts); the established pattern for consolidated read surfaces
  • src/mcp/tools.ts buildToolTable:334 aggregates per-domain *-tools.ts ToolDefinition arrays (contract in src/mcp/tool-contract.ts)
  • schema_apply_mutations is a FALSE LEAD for Task D: it mutates the Brain/_brain.yaml schema pack, not note frontmatter

Conventions:

  • Pure deterministic core builders (clock injected via opts.now, Object.freeze envelopes), thin CLI verb + MCP tool wrappers
  • File-per-item Markdown stores under Brain/ with frontmatter (obligations.ts render/parsePage is the template)
  • Fail-closed errors with guidance (typed error codes, candidate lists on ambiguity), never silent guessing, no misleading fallbacks
  • New agent-driven mutation capabilities gate behind guardrails opt-in flags
  • Tests: bun:test under tests/core/brain/.test.ts, tmp-vault fixtures inline
  • Language-agnostic: no hardcoded natural-language word lists for gating/classification; structural signals and explicit frontmatter fields only; all identifiers and docs in English

Constraints:

  • No behavior change to existing surfaces beyond additive sections/views; existing brain_brief views and morning-brief output must stay byte-compatible for current consumers
  • No new external dependencies
  • Task D write-back must be gated by a guardrails opt-in flag, deterministic, one log event per applied mutation, fail-closed on ambiguous note references
  • Task C marker must reuse or cleanly extend the existing @osb marker grammar rather than inventing a second unrelated syntax; consider that an open loop must SURVIVE scans (stay visible until closed) unlike consumed feedback markers
  • The four features should compose: C's open loops and B's merged timeline become sections of A's dashboard; D shares marker infrastructure with C

Required output format

Produce exactly 3 distinct architectural variants. For each variant:

Variant N:

  • Approach: 2-3 sentences describing the variant.
  • Trade-offs: bullet list of pros and cons.
  • Complexity: small | medium | large
  • Risk: low | medium | high

After the three variants, add exactly one recommendation:

Recommended: Variant N

Rationale: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.

Output nothing outside of these sections.