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
vault-care-bundle - implementation plan
Eight atomic TDD units in the order the chosen variant requires. Each unit ends with a passing-test green bar and a conventional commit on feat/vault-care-bundle. The bundle ships as v0.10.15.
Tasks
Task 1: F7 - NFKC + casefold dedup normaliser (text/normalize.ts)
- Files:
- new:
src/core/brain/text/normalize.ts - modified:
src/core/brain/dedup-hash.ts(swap inlinenormalize("NFC")β callnormalizeForDedup) - new tests:
tests/core/brain/text/normalize.test.ts,tests/core/brain/dedup-hash-unicode.test.ts
- new:
- Acceptance:
bun test tests/core/brain/text/normalize.test.ts tests/core/brain/dedup-hash-unicode.test.tsgreen. Regression cases: fullwidthοΌ‘vs halfwidthAproduce identical hash; CJKγγΉγsurvives normalisation without collapsing to empty string; uppercase / lowercase variants of the same principle produce identical hash. All existing dedup tests still pass. - Depends on: none.
- Commit:
feat(brain): unicode-aware dedup normalisation (NFKC + casefold)
Task 2: F1 - confidence + lifecycle frontmatter atoms (page-meta/)
- Files:
- new:
src/core/brain/page-meta/lifecycle.ts,src/core/brain/page-meta/confidence.ts - modified:
src/core/brain/preference.ts(emit_lifecyclenext to_confidence) - modified:
src/cli/brain/verbs/migrate-frontmatter.ts(add_lifecycle: stableto legacy pages) - new tests:
tests/core/brain/page-meta/lifecycle.test.ts, augmenttests/cli/brain/migrate-frontmatter.test.ts
- new:
- Acceptance: New preferences carry
_lifecycle: stableby default. Migration adds the field to legacy pages idempotently (byte-identical second run).isStale()returns true forlifecycle: stablepages older than 180 days. All existing preference tests still pass. - Depends on: none.
- Commit:
feat(brain): per-page confidence and lifecycle frontmatter
Task 3: F2 - tier frontmatter + ranker weighting
- Files:
- new:
src/core/brain/page-meta/tier.ts - modified:
src/core/search/ranker.ts(extendRankerInputswithtierByDoc, applytierWeight()multiplier inrankResults) - modified:
src/core/brain/preference.ts(accepttier?input, defaultsupporting) - modified:
src/cli/brain/verbs/migrate-frontmatter.ts(addtier: supportingto legacy pages) - new tests:
tests/core/brain/page-meta/tier.test.ts,tests/core/search/ranker-tier.test.ts
- new:
- Acceptance: Ranker multiplies the candidate score by
tierWeight()(core=1.4, supporting=1.0, peripheral=0.6). When every input issupporting(default) the ranker output is bit-identical to pre-change behaviour. Tests pin both regressions. - Depends on: Task 2 (migrate sweep shares the same verb).
- Commit:
feat(brain): page importance tier with ranker weighting
Task 4: F3 - page-level dedup + wikilink patcher
- Files:
- new:
src/core/brain/page-meta/page-id.ts - new:
src/core/brain/page-dedup.ts - new:
src/cli/brain/verbs/page-dedup.ts - modified:
src/cli/brain/verbs/index.ts(register verb) - modified:
src/cli/brain/verbs/migrate-frontmatter.ts(recognise existingmerged_into:pointers) - new tests:
tests/core/brain/page-meta/page-id.test.ts,tests/core/brain/page-dedup.test.ts,tests/cli/brain/page-dedup.test.ts
- new:
- Acceptance:
findDuplicateCandidatesreports near-dup pairs usingnormalizeForDedupon titles + body fingerprint.mergePage(secondary, canonical)writesmerged_into: <id>to secondary and rewrites every[[secondary-title]]reference across the vault. Cycle detection trips at depth 5. Dry-run mode emits diff without touching files. - Depends on: Task 1 (uses
normalizeForDedup), Task 2 (skips pages withlifecycle: archived). - Commit:
feat(brain): page-level dedup with wikilink repatching
Task 5: F5 - token footprint monitor
- Files:
- new:
src/core/brain/text/tokenizer.ts - new:
src/core/brain/token-footprint.ts - new:
src/cli/brain/verbs/token-footprint.ts - modified:
src/cli/brain/verbs/index.ts(register verb) - modified:
src/core/brain/digest.ts(addtokenFootprintsection to digest payload) - new tests:
tests/core/brain/text/tokenizer.test.ts,tests/core/brain/token-footprint.test.ts,tests/cli/brain/token-footprint.test.ts
- new:
- Acceptance:
estimateTokens()returnsceil(utf8_bytes / 4); deterministic, language-agnostic, no script-specific branching.computeTokenFootprint(vault)returns per-category counts (preferences, signals, retired, daily, other). Digest output includesToken footprintsection withtotal,byCategory,exceededWarnThresholdboolean. Default threshold 200_000, overridable viaBRAIN_TOKEN_WARN_THRESHOLDenv var. - Depends on: none (introduces tokenizer that later tasks reuse).
- Commit:
feat(brain): vault token footprint monitor
Task 6: F6 - bounded-token context pack
- Files:
- new:
src/core/brain/context-pack.ts - new:
src/cli/brain/verbs/context-pack.ts - modified:
src/cli/brain/verbs/index.ts(register verb) - modified:
src/mcp/brain-tools.ts(registerbrain_context_packMCP tool) - new tests:
tests/core/brain/context-pack.test.ts,tests/cli/brain/context-pack.test.ts,tests/mcp/context-pack-tool.test.ts
- new:
- Acceptance:
packContext(vault, { maxTokens: 5000 })returns a slice ordered by tier (core β supporting β peripheral) then by recency, stops adding pages when next page would exceed budget. Result payload includestokensUsed,pagesIncluded,pagesSkipped. MCP tool exposes same with JSON-RPC shape consistent with existingbrain_context. - Depends on: Task 3 (tier), Task 5 (tokenizer).
- Commit:
feat(brain): brain_context_pack with token budget
Task 7: F4 - self-healing lint --consolidate
- Files:
- new:
src/core/brain/lint-consolidate.ts - new:
src/cli/brain/verbs/lint.ts - modified:
src/cli/brain/verbs/index.ts(register verb) - new tests:
tests/core/brain/lint-consolidate.test.ts,tests/cli/brain/lint.test.ts
- new:
- Acceptance:
o2b brain lint --consolidateperforms detection-only by default; emits a structured diff (fixes,demotions,alias-normalisations).--applyperforms writes idempotently (second run = no-op). Lifecycle demotion only triggers onstable+ age > 180 days + zero recent reapplies. Broken-link fix followsmerged_intochains. Tag aliases normalise vianormalizeForDedup. - Depends on: Task 1 (normaliser), Task 2 (lifecycle), Task 4 (page-id resolution).
- Commit:
feat(brain): self-healing lint --consolidate with dry-run
Task 8: F8 - ranked maintenance action list
- Files:
- new:
src/core/brain/maintenance/action-scorer.ts - modified:
src/core/brain/digest.ts(add## Actionssection) - modified:
src/core/brain/doctor.ts(emitsuggested_actions:block) - new tests:
tests/core/brain/maintenance/action-scorer.test.ts,tests/core/brain/digest-actions.test.ts
- new:
- Acceptance: Action scorer takes inputs
{ orphans, staleByLifecycle, dedupCandidates, tokenFootprintExceeded, brokenLinks }and returns top-N actions ranked by impact score. Each action hasid,title,impact(number),category,target(path or id). Empty input β empty list (no spurious entries). Digest renders the top 10 as a Markdown bullet list; doctor surfaces same as YAML block. - Depends on: Task 4 (dedup candidates), Task 5 (footprint), Task 7 (broken links via lint).
- Commit:
feat(brain): ranked maintenance action list in digest and doctor
Post-implementation tasks
Task 9: Phase 3 self-review pass
- Run
superpowers:requesting-code-reviewon the branch; apply auto-fix findings. - Run
superpowers:verification-before-completion; capture command output for each "feature works" claim. - Commit:
chore: address self-review findings(only if anything needed fixing).
Task 10: Phase 4 QA
bun test- full suite green.bun run typecheck- no errors.bun run lint- clean.- Manual smoke: run each new CLI verb against a tmpdir vault, confirm output shape.
Task 11: Phase 5 docs
README.md- new "Vault care" paragraph in the features list.CHANGELOG.md- new[0.10.15]entry with capability-first summary + Added / Changed / Notes.- No
[Unreleased]placeholder.
Task 12: Phase 6 PR + auto-merge
- Stop-point: operator confirms diff summary.
git push -u origin feat/vault-care-bundle.gh pr createwith mermaid diagram + capability summary.gh pr merge --auto --squash --delete-branch.
Task 13: Phase 7-8 CodeRabbit + merge wait
- Apply CodeRabbit findings if any; commit
fix: address CodeRabbit review feedback. - Poll
gh pr view --json state,reviewDecisionuntilMERGED.
Task 14: Phase 9 release
- Bump
package.json0.10.14 β 0.10.15. - Generate excalidraw β PNG: three-layer diagram showing atoms β helpers β consumers.
- Stop-point: operator confirms release title + body.
gh release create v0.10.15with PNG + excalidraw assets.
Task 15: Phase 10 tracker tick + kanban close
- Add entry #38 to
/root/vault/Projects/OpenSecondBrain/Features/_summary.md. brain_note: release shipped.- Direct SQL UPDATE on kanban DB: move
t_5de021f1,t_3d157e9b,t_e0d65daa,t_55bd528a,t_68e65e77,t_31c16ba2,t_2e7e3b8d,t_8dd35d10fromtriagetodonewithcompletedevents, summary referencing release URL.