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
Memory Integrity Suite - implementation plan
TDD order: each task starts with failing tests. Features land sequentially (entities -> log shards -> capture boundaries -> fact extraction) because the fact router consumes both the entity kernel and the boundary gate. Format + lint before every commit.
Tasks
Task 1: Entity canonicalization kernel and registry core
- Files:
src/core/brain/entities/{types,canonical,registry,index-builder}.ts,src/core/brain/paths.ts(entities dir),tests/core/brain/entities.canonical.test.ts,tests/core/brain/entities.registry.test.ts - Acceptance: normalize/identity-key/alias resolution pass property fixtures (NFC, case, whitespace); upsert refuses duplicate
(category, normalized name)and duplicate alias claims; archive removes from active lookup, restore returns it; registry rebuilds identically from Markdown alone; files stay Obsidian-valid frontmatter. - Depends on: none
Task 2: Entity surfaces - CLI verbs, MCP read tool, doctor lints, search alias boost, graph relations
- Files:
src/cli/brain/verbs/entity.ts,src/cli/brain.ts,src/cli/command-manifest.ts,src/cli/brain/help-text.ts,src/mcp/brain-tools.ts,src/core/brain/doctor.ts,src/core/search/search.ts,tests/cli/brain.entity.test.ts,tests/mcp/entity-tool.test.ts,tests/core/brain/doctor.entities.test.ts,tests/core/search/entity-alias.test.ts - Acceptance:
o2b brain entity set/get/list/relate/archiveround-trip with--json;brain_entity(view get|list) read-only, registry-guard caps green; doctor flags duplicate claims and broken relations; a query naming an alias boosts chunks naming the canonical entity andwhy_retrievedsays so; relations appear in graph export through existing frontmatter-relations. - Depends on: Task 1
Task 3: Device identity and sharded log writer
- Files:
src/core/config.ts,src/core/brain/paths.ts(shard helpers),src/core/brain/log.ts,tests/core/config.device-id.test.ts,tests/core/brain/log-shards.write.test.ts - Acceptance:
device_idgenerated once into device-local config, validated[a-z0-9-]{1,32}, never read from the vault;appendLogEventwrites<date>.<id>.jsonl+<date>.<id>.mdunder the existing per-dir lock; two writers with different ids never touch the same file; byte-deterministic output for fixed inputs. - Depends on: none
Task 4: Shard-merging readers and scanner refactor
- Files:
src/core/brain/log-jsonl.ts(readLogDaymerge,listLogDates),src/core/brain/doctor.ts(x2 scanners +sync-conflict-loglint),src/core/brain/digest.ts(x2),src/core/brain/digest-agent-summary.ts,src/core/brain/temporal/build-index.ts,tests/core/brain/log-shards.read.test.ts, golden-equivalence updates in existing log/digest/doctor tests - Acceptance: merged read over legacy-only fixtures is byte-identical to pre-change output; mixed legacy+shard fixtures merge in (ts, shardId, line) order; all five scanners produce identical results through
listLogDates; doctor warns on.sync-conflict-*files underBrain/log/. - Depends on: Task 3
Task 5: Capture-boundary config and matcher
- Files:
src/core/brain/policy.ts(+ config template),src/core/brain/types.ts,src/core/brain/capture-boundary.ts,tests/core/brain/policy.sessions.test.ts,tests/core/brain/capture-boundary.test.ts - Acceptance:
sessions.{ignore_patterns,stateless_patterns,ignore_message_patterns}parse with per-key warnings (policy.ts conventions); glob matcher covers*/?/**anchored semantics; invalid message regex degrades to a warning and is skipped; machine-local config unions with vault policy; unconfigured vault behaves bit-identically to today. - Depends on: none
Task 6: Boundary wiring at both seams
- Files:
src/core/brain/session-lifecycle.ts,src/core/brain/sessions/import.ts,src/core/brain/doctor.ts(invalid-capture-patternlint),tests/core/brain/session-lifecycle.boundary.test.ts,tests/core/brain/import-session.boundary.test.ts - Acceptance: ignored session produces no signals/log/markers, only counters in the audit row; stateless session reads fine but writes nothing; suppressed message text never reaches marker extraction and is never persisted; existing behavior unchanged when no patterns configured; counters surface in both result types.
- Depends on: Task 5
Task 7: Regex fact extraction module
- Files:
src/core/brain/fact-extract.ts,src/core/brain/types.ts(source_type: extracted),tests/core/brain/fact-extract.test.ts - Acceptance: 7 pattern families extract from positive fixtures and reject negative fixtures (assistant text, code blocks, quoted speech); only
role: userturns scanned; emitted signals carrysource_type: extracted, family-scoped dedup hash, session ref; second run is a no-op (dedup). - Depends on: none
Task 8: Fact routing - live + batch wiring, entity anchoring, counters
- Files:
src/core/brain/session-lifecycle.ts,src/core/brain/sessions/import.ts,src/core/brain/fact-extract.ts(router),tests/core/brain/fact-extract.routing.test.ts - Acceptance: extraction runs only on turns that pass the boundary gate (pipeline order pinned by a test: suppressed input never extracts); a fact naming a registered entity or alias gets the canonical
entity_idstamped in the signal note;facts_extracted/facts_dedupedcounters in capture and import results and audit rows. - Depends on: Tasks 1, 6, 7
Task 9: Docs
- Files:
README.md,CHANGELOG.md(one v0.35.0 entry bundling the suite),docs/pages the design names - Acceptance: every new surface (entity verbs,
brain_entity,sessions:config, shard layout, extraction families) documented; CHANGELOG follows Keep a Changelog with the release narrative. - Depends on: Tasks 1-8