breferrari/obsidian-mind

Overview

Obsidian Mind is an Obsidian vault template that turns a personal knowledge base into a long‑term memory store for AI coding agents such as Claude Code, Codex CLI, and Gemini CLI. The vault ships a set of hook scripts, command shortcuts and optional semantic‑search integration (QMD) so that every time you start a coding‑assistant session the agent is pre‑loaded with the North Star goals, active projects, recent git changes, open tasks, and a list of files. As you talk, the agent automatically creates and updates notes – meeting minutes, decision records, incident timelines, brag‑doc entries – and keeps the vault tidy.

Key Features

Feature	What it does	Why it matters
Persistent memory across sessions	A SessionStart hook injects curated context (goals, project status, recent changes) at the beginning of every agent conversation.	The agent no longer starts from a blank slate; it remembers past decisions and ongoing work.
Slash‑command shortcuts	Commands like /om-standup, /om-dump, /om-incident‑capture, /om-wrap‑up trigger predefined workflows that create or update notes in specific folders (people, work, decisions, brag docs, etc.).	One‑line commands turn a spoken update into a fully linked set of markdown files.
Automatic note‑linking & validation	Post‑tool hooks validate front‑matter, enforce backlinks, split oversized notes, and flag misplaced files.	Guarantees a clean, graph‑structured knowledge base that is easy to browse and audit.
Optional QMD semantic search	When installed, QMD provides local embeddings, query‑expansion and reranking so the agent can retrieve notes by meaning (e.g., “what did we decide about caching”).	Faster, more accurate recall without sending data to an external API; works offline.
Model Context Protocol (MCP) server	Exposes mcp__qmd__* tools that appear in the agent’s tool menu, letting sub‑agents call the same search functions programmatically.	Makes it easy to add other MCP‑aware tools (ticketing, calendar) later.
Cross‑agent support	Hooks and command files are agent‑agnostic; the same vault works with Claude Code, Codex CLI, Gemini CLI, Antigravity and Grok.	You can switch providers without rebuilding your knowledge base.
ShardMind installer	shardmind install creates a fresh vault, runs a wizard to fill brain/North Star.md, initializes git, and optionally boots QMD.	One‑click setup; the vault can also be cloned directly if you prefer a plain template.
Token‑efficient context handling	Only lightweight excerpts are injected at start; full note contents are fetched on‑demand via QMD or explicit reads.	Keeps the conversation within Claude’s token limits and reduces cost.

How It Works (High‑Level)

1. Vault layout – Core folders such as brain/ (goals, topics), work/ (project notes, ADRs), org/people/, perf/Brag Doc.md, and thinking/session‑logs/ hold the persistent data.
2. Hooks – Node/TypeScript scripts in .claude/scripts/ (also used by Codex/Gemini) run at defined lifecycle events (SessionStart, UserPromptSubmit, PostToolUse, PreCompact, Stop). They inject context, classify messages, validate writes, and perform housekeeping.
3. Claude Code mod – For newer Claude Code versions a small plugin (.claude/skills/obsidian‑mind/) runs inside the model, delivering the injected context as an instruction file and showing concise “vault check” reports after each turn.
4. Semantic retrieval (optional) – Installing QMD creates a local SQLite store with embeddings. The vault’s .mcp.json registers QMD query tools, which the agent can call directly or via the hook‑generated prompts.
5. User interaction – You open the vault in Obsidian, enable the Obsidian CLI, then start the chosen agent (claude, codex, or gemini). From there you simply talk; slash commands trigger the automated workflows described above.

Typical Workflow

# 1️⃣ Install (recommended)
npm install -g shardmind
mkdir my‑vault && cd my‑vault
shardmind install github:breferrari/obsidian‑mind

# 2️⃣ Open the folder in Obsidian, enable the CLI (Settings → General)
# 3️⃣ Start the coding agent in the same directory
claude   # or codex / gemini

Start a session → /om-standup → agent reads North Star, recent git, tasks → you get a concise status.

After a meeting → /om‑dump "…" → notes, decision records, and brag‑doc entries are auto‑created and linked.

Incident → /om‑incident‑capture <slack‑url> → full timeline, people profiles, root‑cause analysis are generated.

End of day → wrap up → vault hygiene check, index update, win spotting.

Who It’s For

• Software engineers or technical leads who already use an AI coding assistant and want the assistant to remember project history, decisions, and personal goals.
• Teams that keep meeting notes, ADRs, and incident reports in Obsidian and would like those artifacts to be automatically linked and searchable by the AI.
• Anyone comfortable with a Node‑based CLI and willing to run a local semantic‑search engine (QMD) for richer recall.

Limitations & Considerations

• The vault is not a standalone AI; it relies on an external coding agent (Claude Code, Codex, Gemini, etc.).
• QMD is optional but required for the advertised “semantic search” experience; without it the system falls back to simple grep, which is still functional but less powerful.
• Hook scripts run with the same permissions as the user; you should review them (especially the Claude Code mod) before trusting the vault.
• Token‑budget handling is tuned for Claude Code’s 10 k‑character hook limit; other agents may have different limits, though the design stays within reasonable bounds.

---

Obsidian Mind therefore provides a concrete, reproducible way to give AI coding agents a durable, searchable memory that lives inside your regular Obsidian knowledge base. It bridges the gap between conversational assistants and the structured notes that engineers already maintain.