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
Recall & Working-Memory Quality Suite - implementation plan
Four atomic units on ONE feature branch (feat/recall-working-memory-quality),
each its own conventional commit, each TDD (failing test first). Order chosen so
the two shared primitives land before their consumers.
Task 1: Selectable recall profiles (Primitive A)
- Files:
src/core/search/profiles.ts(new),src/core/search/types.ts(+recallProfileresolved field, default null),src/core/search/search.ts(apply at theapplyTunedParametersseam),src/cli/search.ts(top-levelo2b search, add--profileflag - NOT a new verb;verbs/profile.tsis the unrelatedo2b brain profiledigest),src/mcp/search-tools.ts(+profilefield onSEARCH_INPUT_SCHEMA), tests:tests/core/search/profiles.test.ts, search byte-identical-OFF test. - Acceptance:
resolveRecallProfile("fast"|"balanced"|"thorough")returns the fixed knob tuple; unknown name throws a typedSearchError("INVALID_INPUT", ...).- With no profile,
search()config is byte-identical to today (asserted). - Explicit profile wins over a persisted self-tuning grid point; both-set and each-alone cases tested.
- CLI
--profileand MCPprofilefield thread through to the resolver.
- Depends on: none.
Task 2: Usage-driven working-memory decay (Primitive B)
- Files:
src/core/brain/continuity/usage-signal.ts(new: usage-signal reader overrecall_telemetryrecords + puredecayWeight(signal, now)),src/core/brain/continuity/read-model.ts(apply weight when flag on),src/core/brain/continuity/types.ts(config/flag if needed), tests:tests/core/brain/continuity/usage-signal.test.ts, read-model decay test + byte-identical-OFF test. - Acceptance:
decayWeightis pure: identical (count, lastAccessAge, now) -> identical value in (0, 1]; frequently-/recently-accessed -> higher weight; stale -> lower.- Usage signal derived only from existing
recall_telemetrycontinuity records; no new mutable counter written to records. - Read-model OFF reproduces current ordering/weights byte-for-byte (asserted).
- No record is deleted or mutated; decay is weighting only.
- Depends on: none.
Task 3: Language-agnostic co-occurrence auto-relate (dream producer)
- Files:
src/core/brain/link-graph/co-occurrence.ts(new: structural co-occurrence scorer + versioned/hashed suggestion artifact, persistence convention mirroringtuning.json), maintenance/dream entry registration,src/cli/brain/verbs/co-occurrence-suggest verb, tests:tests/core/brain/link-graph/co-occurrence.test.ts+ language-agnostic test (non-Latin entities scored identically by structure). - Acceptance:
- Score is document-frequency / PMI-style over canonical-entity -> note incidence; NO natural-language word list anywhere (asserted by a non-Latin / mixed-script fixture producing structurally-identical results).
- Min co-document threshold + top-N cap make output bounded and deterministic (same vault -> same suggestions, hashed).
- Emits derived link suggestions only; note bodies are never modified.
- Re-validate-on-read + fail-soft to empty when the artifact is drifted/missing.
- Depends on: none (independent producer).
Task 4: File-context recall (standalone surface)
- Files:
src/core/brain/file-recall.ts(new: path -> prior-work query reusingsession-focus.tspath-prefix biasing + size gate),src/cli/brain/verbs/file-context verb,src/mcp/new tool + registry, tests:tests/core/brain/file-recall.test.ts,tests/mcp/tool test + tool-count / frozen-name-list updates. - Acceptance:
- Given a file path, returns prior-work hits from the existing search index biased to that path; no LLM call.
- File below the size gate (default 1500 bytes, config field) returns an explicit empty result WITH a reason, never a fabricated hit.
- Path safety: traversal / outside-vault path -> typed error (reuse vault-relative
normalisation), consistent with
session-focus.ts. - MCP tool registered; tool-count and frozen-name-list tests updated in lockstep.
- Depends on: none (uses existing search + session-focus).
Cross-cutting (Phase 4/5)
- Full suite:
bun test,bun run typecheck,bun run lint,bun run scripts/sync-version.ts --check. - Version bump
package.json1.9.0 -> 1.10.0 +bun run scripts/sync-version.ts. - Docs:
CHANGELOG.md(one[1.10.0]entry),README.md,docs/mcp.md. - Byte-identical-OFF assertions per unit are the gate for "additive, no behaviour change".