Obsidian Mind: a vault template that gives coding agents a memory between sessions
A self-organizing Obsidian vault that gives AI coding agents persistent memory. Claude Code, Codex CLI, Gemini CLI.
At a glance
- What is it?
- Obsidian Mind is a TypeScript-backed Obsidian vault template that wires Claude Code, Codex CLI and Gemini CLI into a shared note store. The idea is sound and the install path is concrete, but the retrieval quality depends on an optional QMD index, and the whole thing assumes you already live in Obsidian.
- Who is it for?
- Adopt Obsidian Mind if you already keep notes in Obsidian and run Claude Code in the same directory, because the slash commands map onto a workflow you have. Do not adopt it if you want an agent memory layer that works without a vault application, or if you cannot install QMD and accept grep-quality retrieval.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The forgetting problem Obsidian Mind is aimed at
Coding agents start each session with no memory of the last one. The README states the problem directly: no context on your goals, your team, your patterns, your wins, and knowledge that never compounds. Obsidian Mind's answer is to put that context in a vault of Markdown files and have the agent read and write them through hooks and slash commands. The intended user is someone who already writes things down, holds one-on-one meetings, tracks decisions, and wants the agent to file the output rather than lose it. The README's example is a manager with an active project, a blocked contract, and a 1:1 the next day. That is a specific persona, not a general developer. If your work produces no meeting notes, no decision records and no brag doc, most of the vault structure has nothing to hold.
How the vault, the hooks and the commands fit together
The repository is a vault template plus agent configuration. Notes live under folders such as brain, work, org, perf and 1-1, and `brain/North Star.md` holds your goals. Slash commands are the entry points: `/om-standup` loads the North Star, active projects, open tasks and recent git changes; `/om-dump` takes free text and fans it out into person notes, meeting notes, decision records and brag doc entries; `/om-incident-capture` takes a Slack URL and, per the README, has a slack-archaeologist read messages, threads and profiles while a people-profiler creates notes for new people. Subagents named context-loader, review-prep and brag-spotter do retrieval work. The SessionStart hook is what makes the memory persistent across sessions rather than per-command. Claude Code gets what the README calls full support; Codex CLI and Gemini CLI get hooks plus commands. Same vault, same commands, three hosts. The design is file-first: nothing is stored in a database, so the memory is inspectable and editable in Obsidian itself.
QMD is optional in name only
The README is unusually honest here: QMD is optional in the strict sense because the vault falls back to grep plus the Obsidian CLI, but the experience is meaningfully better with it. Semantic recall is the difference between finding a note titled "Redis Migration ADR" when you ask what was decided about caching, and not finding it. QMD is registered as a Model Context Protocol server in `.mcp.json`, which exposes `mcp__qmd__query`, `mcp__qmd__get` and `mcp__qmd__multi_get` as tools alongside Read and Edit, and the README notes that subagents, slash commands and the main conversation all call the same typed contract. Installation is two commands: `npm install -g @tobilu/qmd` and `node --experimental-strip-types .scripts/qmd-bootstrap.ts`. The bootstrap is described as idempotent and resolves the index name from the `qmd_index` field in `vault-manifest.json` when set, otherwise from the slugified vault folder name. It reads `qmd_context`, registers the collection, attaches context, and builds the index and embeddings. The `--experimental-strip-types` flag is a signal that this path depends on a Node feature that is still labelled experimental, and the README requires Node 22 or newer.
Installing it: two routes with different consequences
The recommended route is ShardMind, the author's package manager for vault templates. You run `npm install -g shardmind`, then `mkdir my-vault && cd my-vault`, then `shardmind install github:breferrari/obsidian-mind`. The install writes into the current directory, which is why the fresh folder matters. The wizard collects your name, organization, vault purpose, which agents to include, and whether to enable QMD, then initializes git, optionally bootstraps QMD, and personalizes `brain/North Star.md`. The alternative is `git clone https://github.com/breferrari/obsidian-mind.git` or using the repository as a GitHub template, which skips the wizard and leaves you to fill in the North Star file yourself. Both routes end with the same four steps: open the folder as an Obsidian vault, enable the Obsidian CLI under Settings, General (Obsidian 1.12 or newer), run `claude`, `codex` or `gemini` in the vault directory, and start talking. ShardMind adds a `.shardmind/` sidecar for the wizard, optional modules and three-way-merge upgrades. The README claims that with every value at its default the install is byte-equivalent to a clone, and that deleting `.shardmind/` and `shard-values.yaml` leaves a working vault. That claim is testable and worth testing before you depend on it.
Where this design breaks down
The dependency chain is the main limitation. You need Obsidian 1.12 or newer, the Obsidian CLI enabled, Node 22 or newer, and a working agent CLI, and the agent has to run inside the vault directory for the hooks and relative paths to resolve. That is a lot of prerequisites for a memory layer. The fallback retrieval path is grep, which means the quality of recall degrades sharply if QMD is absent or the bootstrap fails. The README's own framing concedes this. There is also a scope mismatch: a vault organised around 1-1s, brag docs and people notes suits engineering managers and staff-plus engineers more than it suits a solo developer shipping a library, who will find most folders empty. And because the memory is plain Markdown that the agent edits, a bad `/om-dump` writes bad notes into the same store the next session reads. There is no staging area described in the material. The README does not document conflict handling when the agent and a human edit the same note, and the supplied material does not describe how hooks behave on Windows.
How it differs from a memory server or a plain notes folder
The obvious alternative is a memory layer that lives beside the agent rather than inside a note-taking application, such as an MCP memory server backed by a database. The difference in approach is structural. A memory server stores structured records and exposes retrieval as a tool call; Obsidian Mind stores prose in a vault you can open, read, link and edit by hand, and exposes the vault to the agent through hooks, slash commands and a QMD MCP server. The trade-off is legibility against precision. Vault files are easy to audit and easy to fix with a text editor, but retrieval quality rides on semantic search over unstructured notes. A database memory server gives tighter query semantics but the contents are opaque unless you build a viewer. A third option, which is what most people actually do, is keeping a `CLAUDE.md` and a notes folder and pasting context in manually. Obsidian Mind automates that paste, and the automation is the product. If you are not already an Obsidian user, the vault is a cost rather than a benefit.
Maintenance, upgrades and the MIT licence
The project is on version 8.4.0, with 8.3.6 and 8.3.5 landing in the preceding weeks, so the release cadence is fast enough that you should expect to read release notes before upgrading. ShardMind's three-way-merge upgrades are the intended mechanism for pulling changes into a personalised vault, which is the reason to accept the `.shardmind/` sidecar despite the extra directory. Direct cloners have no merge path and will be diffing by hand. The licence is MIT, which permits commercial use and modification; the repository ships a LICENSE file. That is a statement about the licence text, not legal advice, and if the vault will hold employer data you should check your own policy on where meeting notes and personnel information are stored. The bigger ongoing cost is not code, it is content: the vault is only as useful as the notes you and the agent put into it, and the README's workflow assumes you feed it regularly.
Editorial conclusion
Adopt Obsidian Mind if you already keep notes in Obsidian and run Claude Code in the same directory, because the slash commands map onto a workflow you have. Do not adopt it if you want an agent memory layer that works without a vault application, or if you cannot install QMD and accept grep-quality retrieval. Before committing, verify that Obsidian is at 1.12 or newer, that the Obsidian CLI toggle exists under Settings, General, and that `node --experimental-strip-types .scripts/qmd-bootstrap.ts` completes against your vault folder name.
Community notes