Model or dataset
breferrari/obsidian-mind avatar
breferrari/obsidian-mind

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.

5,537 stars615 forksTypeScriptMIT

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 29 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 November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • breferrari/obsidian-mind5,537 ★ · +913
Star history
Repository2026-09-102026-11-15
breferrari/obsidian-mind4.6k5.5k

913 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial 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 work/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. 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: notes are Markdown files in the vault, 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.

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.js, 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.

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 10.0.0, with 9.1.0 and 9.0.1 landing in the preceding week, 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. 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.

Frequently asked questions

What is Obsidian Mind in this repository?

A self-organising Obsidian vault template that gives AI coding agents persistent memory. It is built for Claude Code with working hooks for Codex CLI and Gemini CLI, and it handles notes, links, indexes and performance tracking so that each conversation builds on the last.

How do I install Obsidian Mind?

Clone the repository directly, use it as a GitHub template, or install the ShardMind package manager with npm install -g shardmind and run shardmind install github:breferrari/obsidian-mind inside a fresh folder. The wizard personalises brain/North Star.md, and with default values the result is byte-equivalent to a clone.

Do I need QMD for Obsidian Mind to work?

No. QMD is optional in the strict sense and the vault falls back to grep plus the Obsidian CLI. The README says the experience is meaningfully better with it, because it adds semantic recall and gives subagents such as context-loader and brag-spotter sharper context.

What are the slash commands in Obsidian Mind?

/om-standup loads the North Star, active projects, open tasks and recent git changes. /om-dump captures a meeting into person notes, a one to one record, a decision record and the brag doc, /om-incident-capture reconstructs an incident from a Slack link, and wrapping up verifies links, updates indexes and looks for uncaptured wins.

What does Obsidian Mind require before it works?

Obsidian 1.12 or newer with the Obsidian CLI enabled in Settings under General, Node.js, and then you run claude, codex or gemini from the vault directory. READMEs are provided in English, Japanese, Chinese and Korean.

Official sources

  1. breferrari/obsidian-mind on GitHub
  2. Issues
  3. License: MIT
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/breferrari-obsidian-mind.svg)](https://hysenlabs.com/projects/breferrari-obsidian-mind)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/breferrari-obsidian-mind.svg)](https://hysenlabs.com/projects/breferrari-obsidian-mind)

Was this useful?