Obsidian Mind: Persistent Memory for Claude Code, Codex CLI and Gemini CLI

The problem: an agent that starts every session from zero

The README states the problem plainly: AI coding agents forget, so every session begins with no context on your goals, your team, your patterns or your wins. You re-explain the same things, and decisions made three conversations ago are gone. Obsidian Mind's answer is to make the memory a plain Obsidian vault sitting in the directory where you run the agent. The target user is specific: someone who already drives an agent from a terminal, keeps notes somewhere, and is willing to let the agent write into those notes. The repository describes the vault as "An Obsidian vault that gives AI coding agents persistent memory," built for Claude Code with working hooks for Codex CLI and Gemini CLI. If you only use a chat window in a browser, the design does not reach you.

How the vault, hooks and MCP fit together

The mechanism is a directory of Markdown folders plus per-agent configuration. The top level of the repository holds brain/, work/, org/, perf/, thinking/, reference/, templates/ and bases/, alongside agent configuration in .claude/, .codex/ and .gemini/. A vault-manifest.json at the root carries vault-level settings, and .mcp.json registers QMD as a Model Context Protocol server. The README says that with QMD installed, mcp__qmd__query, mcp__qmd__get and mcp__qmd__multi_get appear in the agent's tool menu next to Read and Edit, and that subagents, slash commands and the main conversation all call the same typed contract. Without QMD the vault falls back to grep plus the Obsidian CLI, which the README presents as the lesser path. The SessionStart hook is the other half: it reads the manifest so a session can begin with context already loaded. A CLAUDE.md file instructs the agent to consult brain/ guidance through QMD when a conversation touches a listed topic. That is the whole architecture: Markdown as storage, hooks as the entry point, MCP as the retrieval tool, and a manifest as the shared source of truth.

Installing Obsidian Mind and running a first session

The README gives two install paths. The recommended one uses ShardMind, described as a package manager for Obsidian vault templates. It writes into the current directory, so create a fresh folder first.

npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind

The wizard collects your name, organization, vault purpose, which agents to include, and whether to enable QMD. ShardMind then initializes git, optionally bootstraps QMD, and personalizes brain/North Star.md with your answers. The README notes that with every value at its default the install is byte-equivalent to git clone, and that deleting .shardmind/ and shard-values.yaml from the installed vault leaves it working, because ShardMind is additive rather than load-bearing. The second path is a plain clone, which skips the wizard and leaves brain/North Star.md for you to fill in.

git clone https://github.com/breferrari/obsidian-mind.git

After either path the README lists four steps: open the folder as an Obsidian vault, enable the Obsidian CLI in Settings, General (Obsidian 1.12 or newer), run claude, codex or gemini in the vault directory, then start talking about work. The first real use is the standup command, which the README shows loading the North Star, active projects, open tasks and recent git changes.

/om-standup

The README's example output names two active projects, an auth refactor blocked on an API contract, and a 1:1 later that day. A second command, /om-dump, takes free text after a meeting and, per the README, updates a person note, creates a dated 1-1 note, creates a decision record, adds a line to perf/Brag Doc.md, and updates the relevant project note. If you want semantic recall on top, the README gives the QMD install and an idempotent bootstrap script.

npm install -g @tobilu/qmd
node --experimental-strip-types .scripts/qmd-bootstrap.ts

What QMD adds, and what you lose without it

QMD is optional in the strict sense, and the README is honest that it is where most of the agent's retrieval intelligence comes from. The concrete difference is recall by meaning rather than by string: the README's own example is finding "what did we decide about caching" when the note is titled "Redis Migration ADR." Without it you are left with grep plus the Obsidian CLI, which means your agent finds what you can find with a keyword. The README also claims subagents such as context-loader, review-prep and brag-spotter consult QMD first and fall back to grep. That fallback matters: it means the vault degrades rather than breaks when QMD is absent, but it also means the quality of retrieval depends on a second global npm package and an index build. The bootstrap resolves the index name from the qmd_index field in vault-manifest.json when set, otherwise from the slugified vault folder name. Two components read that same value, so if the manifest and the folder disagree with an existing index, that is where to look first.

Where Obsidian Mind is the wrong tool

The template assumes a local vault directory that the agent can read and write, plus a desktop Obsidian install at 1.12 or newer with the Obsidian CLI switched on. If your team runs agents in containers or on remote runners without that folder mounted, the hooks have nothing to read. If you do not use Obsidian at all, you are adopting a note-taking application to get agent memory, which is a large dependency for the benefit. There is also a maintenance question the README does not answer: the agent writes into your notes, and the repository does not document rollback or an undo path for a bad /om-dump. Git is initialized by the ShardMind wizard, so version control is the practical recovery mechanism, but that comes from the install step rather than from a documented feature. Finally, the README describes full support for Claude Code and hooks plus commands for Codex CLI and Gemini CLI. That phrasing suggests the three agents are not equally covered, and the README does not enumerate the gaps.

Alternatives and the real difference in approach

The closest comparison the README itself draws is between shardmind install and git clone, and the difference is genuinely small: the wizard personalizes brain/North Star.md and can bootstrap QMD, while the clone leaves both to you. Outside the repository, the honest alternative is a memory layer built into the agent rather than a vault beside it, where context is stored by the tool and not as Markdown you own. Obsidian Mind takes the opposite position: memory is files on disk, readable in Obsidian, diffable in git, and portable between Claude Code, Codex CLI and Gemini CLI because all three point at the same folder. The trade is that you maintain the vault, and retrieval quality rides on an optional external index. If you want memory you can open and edit by hand, the file-based approach is the reason to pick this. If you want memory you never think about, it is the reason to look elsewhere.

Maintenance, upgrades and the MIT licence

The last push to the default branch was on 2026-09-02, the same day as the v8.4.0 release. Two earlier releases, v8.3.6 and v8.3.5, landed on 2026-08-23 and 2026-08-17, so the project has shipped three releases in roughly two weeks. The repository is not archived. The README describes three-way-merge upgrades as a ShardMind feature, which is the upgrade story the template offers; the README does not document what happens to a merge conflict inside a note the agent wrote. The project is MIT licensed, which permits commercial use and modification, but the licence text itself is the authority and this is not legal advice. One practical licence note: QMD is a separate package installed globally, so its terms apply independently of the vault. The Node badge in the README lists Node 22 or newer, which is a floor worth checking before you start.

Editorial conclusion

Adopt Obsidian Mind if you already run Claude Code, Codex CLI or Gemini CLI from a terminal and want the agent to carry context between sessions; the vault is the same for all three, so trying it costs one folder. Skip it if you want a hosted memory service, if you do not use Obsidian, or if your agent runs somewhere that cannot read a local vault directory. Before relying on it, verify two things yourself: that your Obsidian build is 1.12 or newer with the Obsidian CLI enabled in Settings, and that the QMD bootstrap resolves the index name you expect from the qmd_index field in vault-manifest.json, since that field is the single source the SessionStart hook and the .mcp.json wrapper both read.

Frequently asked questions

Official sources

1. breferrari/obsidian-mind on GitHub
2. Issues
3. License: MIT
4. README
5. Releases