# obsidian-mind Audit Report **Date**: 2026-05-24 **Repo**: https://github.com/breferrari/obsidian-mind **Auditor**: Aria sub-agent (research-only, no installs) --- ## 1. What Is It obsidian-mind is an Obsidian vault *template* — not a plugin — designed to give AI coding agents (Claude Code, Codex CLI, Gemini CLI) persistent memory across sessions. v6.1 (2026-05-18), 2.7k stars, 334 forks, MIT, TypeScript. It ships a structured vault directory tree, 18 Claude Code slash commands (`/om-standup`, `/om-wrap-up`, `/om-dump`, etc.), 9 specialized subagents, and a TypeScript hook layer wired to 5 Claude Code lifecycle events (SessionStart, UserPromptSubmit, PostToolUse, PreCompact, Stop). Core claim: "AI coding agents forget — this gives them a brain." Semantic search is provided via `@tobilu/qmd`, an MCP server doing hybrid BM25 + local vector (gemma-300M via node-llama-cpp) + LLM reranking (Qwen3-1.7B), all on-device, SQLite-backed. --- ## 2. Maturity & Tech Stack | Dimension | Value | |---|---| | Stars | 2,700 | | Forks | 334 | | Latest release | v6.1 — 2026-05-18 (active) | | License | MIT | | Language | TypeScript 83%, JS 17% | | Archived | No | | Dependencies | `@tobilu/qmd` (npm), `node-llama-cpp` (local inference), ShardMind (package manager) | ### Lifecycle Hook Architecture - **SessionStart**: loads North Star goals (top 30 lines), brain directory index, git log last 48h, open tasks, active work list, full vault file index → ~2,000 tokens injected - **UserPromptSubmit**: classify-message (pure pattern-matching against `lib/signals.ts`) → adds routing hints as `additionalContext` - **PostToolUse**: validate-write checks frontmatter completeness and wikilink presence on every vault write - **PreCompact**: backs up transcript to `thinking/session-logs/` (30-file rolling retention), triggers QMD reindex - **Stop**: displays hygiene checklist, triggers debounced QMD refresh --- ## 3. What's New vs Aria's Existing Brain Stack ### Aria already has: - Obsidian brain vault (800+ notes) - BM25 brain-search with recency scoring - aria-brain MCP server - Insight-Register - Memory consolidation (sleep + compaction hooks) - aria-wrap-up skill (session end) - context-save / context-restore skills - Lifecycle-adjacent hooks (pre-output-critic, post-task hooks) ### What obsidian-mind does that Aria does NOT have: **A. PostToolUse vault write validation (high value)** Every Write/Edit inside the vault immediately triggers frontmatter + wikilink hygiene checks. This is automated, inline, and prevents note rot at write time. Aria has no equivalent — Brain notes can be written with missing frontmatter or dead links and nobody catches it until a manual audit. **B. Tiered token injection (medium value)** 2,000-token "always-on" context at SessionStart (goals + git delta + open tasks) is assembled programmatically from live state, not from a static memory file. Aria's MEMORY.md is static per-session. The obsidian-mind pattern assembles fresh context dynamically (including recent git changes) every session boot. **C. Message classifier as hook (low-medium value)** UserPromptSubmit hook does lightweight signal-pattern matching to pre-route messages to appropriate note categories. Aria does not have this hook. Its equivalent is Aria's own skill-routing intelligence, which is heavier (LLM judgment vs. regex patterns). **D. PreCompact transcript backup with rolling retention (medium value)** Auto-save of session transcript before compaction, 30-file retention in vault. Aria has PreCompact hooks for memory distillation, but transcript backup is not currently done. **E. Local hybrid search: BM25 + on-device vector + LLM rerank via QMD (high value if QMD is trustworthy)** Aria has BM25 only. QMD adds 768-dim embeddings (gemma-300M) + Qwen3 reranker, fully local, SQLite-backed, MCP-exposed. This is a meaningful recall improvement, especially for semantic queries where terminology varies across notes. The fork `qmd-bedrock` demonstrates the embedding backend is swappable. **F. Structured subagent roster with specialized scopes (medium value)** `brag-spotter`, `cross-linker`, `vault-librarian`, `slack-archaeologist`, `vault-migrator` — each scoped to a narrow heavy operation that would pollute the main conversation context. Aria has skill-based subagent patterns but not vault-maintenance-specific agents. **G. vault-manifest.json schema enforcement (low value — Aria already has Brain structure)** Version fingerprints + frontmatter schema per note type. Aria's Brain is more organic; this would add rigidity that could be detrimental given Aria's 800-note legacy. --- ## 4. Pattern Adoption Recommendations (Ranked) ### Priority 1 — PostToolUse write validator (adopt immediately) **Pattern**: After every Write/Edit to `/root/aria/brain/`, fire a lightweight hook that checks (a) frontmatter present with required fields, (b) wikilinks aren't broken. Emit `additionalContext` warning if violations found — forces agent to fix before moving on. **How**: Add a `PostToolUse` hook in `/root/.claude/settings.json` pointing to a new script `/root/aria/hooks/validate-brain-write.ts` (or bash). Filter on `tool_name in [Write, Edit]` + `file_path contains /aria/brain/`. **Effort**: ~2h. High ROI: prevents note rot at source. ### Priority 2 — Dynamic SessionStart context assembly (consider for Sprint 6+) **Pattern**: Replace or augment MEMORY.md static injection with a programmatic session-start hook that reads: (a) active KAR issues from Linear or local cache, (b) recent git delta in Kadi-v2, (c) top-N unresolved Insight-Register items. Limits to ~2,000 tokens. **How**: Extend existing PreCompact/session hooks or add a new SessionStart hook in settings.json. **Effort**: ~4h. Medium ROI: reduces context stale-ness at session open. ### Priority 3 — PreCompact transcript backup **Pattern**: Before compaction, copy the `.jsonl` transcript to `~/aria/state/session-logs/session_.jsonl` with 30-file rolling retention. **How**: Add to existing PreCompact hook logic. **Effort**: ~30 min. Low effort, protects against compaction-induced loss. ### Priority 4 — Evaluate QMD as brain-search upgrade **Pattern**: Replace or augment aria's BM25 brain-search with `@tobilu/qmd` (local hybrid BM25 + gemma-300M embeddings + Qwen3 reranker, MCP-exposed). Requires `node-llama-cpp` + model downloads (~1-2GB). **Consideration**: `@tobilu/qmd` is not on a publicly accessible GitHub repo (npm-only, private or unlisted). The fork `qmd-bedrock` suggests the upstream is real but low-visibility. **Do not adopt until package provenance is confirmed.** If `@tobilu/qmd` opens source or is verifiable, this is the single highest-value upgrade to Aria's recall quality. **Effort to evaluate**: 1h research; if adopting: 4-6h. ### Priority 5 — vault-maintenance subagents **Pattern**: Create Aria equivalents of `vault-librarian` (finds orphaned notes, broken links) and `cross-linker` (suggests wikilinks between existing notes) as Aria skills triggered periodically or on-demand. **Effort**: ~3h per agent. Lower priority — Aria's Brain structure is more AI-assistant-centric than engineer-work-log, so the exact agents don't map 1:1. --- ## 5. Aria-First Benefit Aria's Brain vault is its single most important differentiable asset (800+ notes, BM25 search, MCP-exposed). The vault write validator (Priority 1) would guarantee structural integrity as the vault grows toward and beyond 1,000 notes. Combined with QMD (Priority 4, if provenance clears), Aria gains semantic search that BM25 alone cannot provide — critical when notes use varied terminology for the same concept (e.g., "compaction" vs. "context window management" vs. "memory consolidation"). For the Aria-as-product angle: the structured lifecycle hook architecture in obsidian-mind is the cleanest public reference implementation for "AI agent with persistent Obsidian vault" and demonstrates that this pattern has 2.7k stars of market validation. --- ## 6. Prompt Injection / Security Scan | Vector | Status | Notes | |---|---|---| | CLAUDE.md instructions | CLEAN | No external URLs, no curl\|bash, no data exfiltration, no suspicious LLM redirects | | session-start.ts | CLEAN | Local fs only; QMD spawn is local binary, fire-and-forget | | classify-message.ts | CLEAN | Pure local pattern-matching, no network, no LLM call | | pre-compact.ts | CLEAN | Local file copy only | | validate-write.ts | CLEAN | Local fs read only | | stop-checklist.ts | CLEAN | Local only, recursive-execution guard present | | vault-manifest.json | CLEAN | Static config, no URLs | | brag-spotter.md | CLEAN | Local file ops + git only | | ShardMind (.shardmind/shard.yaml) | LOW RISK | References one GitHub raw URL for JSON schema validation only; no registry calls or auth tokens | | @tobilu/qmd | UNVERIFIABLE | npm package, GitHub repo not publicly accessible; provenance unclear. Do not install without source code review. | | Installation method | OBSERVE | `npm install -g shardmind` + `shardmind install github:...` is a script-runner pattern. The ShardMind npm package itself is an unreviewed dependency. Review before running. | **No prompt injection vectors found in the readable source.** The main unresolved risk is `@tobilu/qmd` (private/npm-only) and the `shardmind` npm package — both require independent source audit before any installation on the Aria VPS. --- ## 7. Verdict **VERDICT: pattern-adoption-worthy** **Confidence: HIGH (90%)** **Reason**: obsidian-mind is a well-engineered, actively maintained reference implementation of exactly what Aria IS (AI agent + Obsidian vault + lifecycle hooks). It introduces no architecturally novel concepts, but the PostToolUse write validator and dynamic SessionStart context assembly are concrete, copy-worthy patterns that Aria currently lacks. The semantic search upgrade (QMD) is the highest-potential capability gap but requires provenance verification first. Do not install the tool — adopt the patterns. --- ## 8. Linear / Action Items | Item | Priority | Effort | |---|---|---| | KAR-NEW: PostToolUse brain-write validator hook | P1 | ~2h | | KAR-NEW: Verify @tobilu/qmd npm provenance | P2 | ~1h | | KAR-NEW: PreCompact transcript backup (30-file rolling) | P3 | ~30m | | KAR-NEW: Dynamic SessionStart context assembly (Sprint 6+) | P3 | ~4h | | KAR-NEW: vault-librarian + cross-linker Aria skills | P4 | ~6h | --- *Audit complete. Research only — nothing installed, no code written.*