Skip to content
Back to search

obsidian-skills

MarketplaceWorks with Claude CodeGitHub

A self-organizing Obsidian vault that gives AI coding agents persistent memory. Claude Code, Codex CLI, Gemini CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/breferrari-obsidian-mind/badge.svg)](/listings/breferrari-obsidian-mind)

HTML

<a href="/listings/breferrari-obsidian-mind"><img src="/api/listings/breferrari-obsidian-mind/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

πŸ“¦ Install via ShardMind (recommended)

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

`shardmind install` writes into the current directory, so create and enter a fresh folder first. The wizard collects your name, organization, vault purpose, agents to include, and whether to enable QMD; ShardMind then initializes git, optionally bootstraps QMD, and personalizes `brain/North Star.md` with your answers. Then:

1. Open the installed folder as an **Obsidian vault** 2. Enable the **Obsidian CLI** in Settings β†’ General (requires Obsidian 1.12+) 3. Run your agent in the vault directory: **`claude`**, **`codex`**, or **`gemini`** 4. Start talking about work

[ShardMind](https://github.com/breferrari/shardmind) is the package manager for Obsidian vault templates. The install adds a `.shardmind/` sidecar that powers the wizard, optional modules (skip what you don't use), and three-way-merge upgrades. With every value at its default the install is byte-equivalent to `git clone` β€” clone-UX is preserved exactly. Delete `.shardmind/` and `shard-values.yaml` from the installed vault and it keeps working: ShardMind is additive, not load-bearing.

Or clone directly

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

Or use it as a **GitHub template**. Skip the wizard, get the bare template. Then run through the same 4 steps above, plus fill in **`brain/North Star.md`** with your goals (the ShardMind wizard does this for you).

πŸ” Recommended: QMD Semantic Search

QMD is where most of the agent's retrieval intelligence comes from. Optional in the strict sense β€” the vault falls back to grep + the Obsidian CLI β€” but the experience is meaningfully better with it:

- **Semantic recall.** Find "what did we decide about caching" even when the note is titled "Redis Migration ADR." - **Brain topics available on demand.** Claude is instructed (via `CLAUDE.md`) to consult `brain/` guidance through QMD when the conversation touches a listed topic. - **Subagents get sharper context.** `context-loader`, `review-prep`, `brag-spotter`, and friends consult QMD first, then fall back to grep. - **Native agent tools via MCP.** Registered as a [Model Context Protocol](https://modelcontextprotocol.io) server in `.mcp.json` β€” when QMD is installed, `mcp__qmd__query`, `mcp__qmd__get`, and `mcp__qmd__multi_get` appear in the agent's tool menu alongside Read and Edit. Subagents, slash commands, and the main conversation all call the same typed contract. Add another MCP-aware tool later (a database, a ticketing system, a calendar) and it plugs in the same way.

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

The bootstrap is idempotent β€” safe to re-run. It resolves this vault's index name β€” the `qmd_index` field from `vault-manifest.json` when set, otherwise the vault folder name slugified β€” reads `qmd_context`, registers the collection, attaches the context, and builds the index + embeddings. The SessionStart hook and `.mcp.json` wrapper both read the same manifest field, so CLI queries, the MCP server, and the re-index all scope to the same named SQLite store. This isolates the vault from any other QMD-using vault on the same machine.

If you want to use a different index name (for example, one vault per engineer on a shared workstation), edit `qmd_index` in `vault-manifest.json` before running the bootstrap. Once the store is populated, always pass `--index <name>` to the CLI:

qmd --index obsidian-mind query "what did we decide about caching"
qmd --index obsidian-mind update   # after bulk edits
qmd --index obsidian-mind embed    # after many new notes

How it works under the hood

QMD runs **three small models locally**, so there is no API key to set up, no per-query cost, and it works offline:

| model | size | job | |---|---|---|

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json Β· Manifest Β· 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "obsidian-skills",
  3. "owner": {
  4. "name": "Steph Ango",
  5. "url": "https://stephango.com/"
  6. },
  7. "plugins": [
  8. {
  9. "name": "obsidian",
  10. "source": "./",
  11. "description": "Claude Skills for Obsidian",
  12. "version": "1.0.1"
  13. }
  14. ]
  15. }
README.md Β· README Β· 737 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. 🌐 **English** | [ζ—₯本θͺž](README.ja.md) | [δΈ­ζ–‡](README.zh-CN.md) | [ν•œκ΅­μ–΄](README.ko.md)
  2. <p align="center">
  3. <img src="obsidian-mind-logo.png" alt="Obsidian Mind" width="120">
  4. </p>
  5. <h1 align="center">Obsidian Mind</h1>
  6. [![Claude Code](https://img.shields.io/badge/claude%20code-full%20support-D97706)](https://docs.anthropic.com/en/docs/claude-code)
  7. [![Codex CLI](https://img.shields.io/badge/codex%20cli-hooks%20%2B%20commands-10A37F)](https://github.com/openai/codex)
  8. [![Gemini CLI](https://img.shields.io/badge/gemini%20cli-hooks%20%2B%20commands-4285F4)](https://github.com/google-gemini/gemini-cli)
  9. [![Obsidian](https://img.shields.io/badge/obsidian-1.12%2B-7C3AED)](https://obsidian.md)
  10. [![Obsidian CLI](https://img.shields.io/badge/obsidian--cli-integrated-E6E6E6)](https://github.com/kepano/obsidian-cli)
  11. [![Obsidian Skills](https://img.shields.io/badge/obsidian--skills-integrated-8B5CF6)](https://github.com/kepano/obsidian-skills)
  12. [![QMD](https://img.shields.io/badge/qmd-semantic%20search-FF6B6B)](https://github.com/tobi/qmd)
  13. [![Node](https://img.shields.io/badge/node-22%2B-339933)](https://nodejs.org)
  14. [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  15. > **An Obsidian vault that gives AI coding agents persistent memory.** Built for Claude Code, with working hooks for Codex CLI and Gemini CLI. Start a session, talk about your day, and the agent handles the rest β€” notes, links, indexes, performance tracking. Every conversation builds on the last.
  16. ---
  17. ## πŸ”΄ The Problem
  18. AI coding agents are powerful, but they forget. Every session starts from zero β€” no context on your goals, your team, your patterns, your wins. You re-explain the same things. You lose decisions made three conversations ago. The knowledge never compounds.
  19. ## 🟒 The Solution
  20. Give your agent a brain.
  21. ```
  22. You: "start session"
  23. Agent: *reads North Star, checks active projects, scans recent memories*
  24. Agent: "You're working on Project Alpha, blocked on the BE contract.
  25. Last session you decided to split the coordinator. Your 1:1
  26. with your manager is tomorrow β€” review brief is ready."
  27. ```
  28. Works with **Claude Code** (full support), **Codex CLI**, and **Gemini CLI** β€” same hooks, same commands, same vault.
  29. Install via `shardmind install` or `git clone` β€” same vault either way.
  30. ---
  31. ## ⚑ See It In Action
  32. <p align="center">
  33. <img src="obsidian-mind-demo.gif" alt="Obsidian Mind demo β€” standup and dump commands" width="800">
  34. </p>
  35. **Morning kickoff:**
  36. ```bash
  37. /om-standup
  38. # β†’ loads North Star, active projects, open tasks, recent git changes
  39. # β†’ "You have 2 active projects. The auth refactor is blocked on API contract.
  40. # Your 1:1 with Sarah is at 2pm β€” last time she flagged observability."
  41. ```
  42. **Brain dump after a meeting:**
  43. ```bash
  44. /om-dump Just had a 1:1 with Sarah. She's happy with the auth work but wants
  45. us to add error monitoring before release. Also, Tom mentioned the cache
  46. migration is deferred to Q2 β€” we decided to focus on the API contract first.
  47. Decision: defer Redis migration. Win: Sarah praised the auth architecture.
  48. ```
  49. ```
  50. β†’ Updated org/people/Sarah Chen.md with meeting context
  51. β†’ Created work/1-1/Sarah 2026-03-26.md with key takeaways
  52. β†’ Created Decision Record: "Defer Redis migration to Q2"
  53. β†’ Added to perf/Brag Doc.md: "Auth architecture praised by manager"
  54. β†’ Updated work/active/Auth Refactor.md with error monitoring task
  55. ```
  56. **Incident response:**
  57. ```bash
  58. /om-incident-capture https://slack.com/archives/C0INCIDENT/p123456
  59. # β†’ slack-archaeologist reads every message, thread, and profile
  60. # β†’ people-profiler creates notes for new people involved
  61. # β†’ Full timeline, root cause analysis, brag doc entry
  62. ```
  63. **End of day:**
  64. ```
  65. You: "wrap up"
  66. # β†’ verifies all notes have links
  67. # β†’ updates indexes
  68. # β†’ brag-spotter finds uncaptured wins
  69. # β†’ suggests improvements
  70. ```
  71. ---
  72. ## πŸš€ Quick Start
  73. ### πŸ“¦ Install via ShardMind (recommended)
  74. ```bash
  75. npm install -g shardmind
  76. mkdir my-vault && cd my-vault
  77. shardmind install github:breferrari/obsidian-mind
  78. ```
  79. `shardmind install` writes into the current directory, so create and enter a fresh folder first. The wizard collects your name, organization, vault purpose, agents to include, and whether to enable QMD; ShardMind then initializes git, optionally bootstraps QMD, and personalizes `brain/North Star.md` with your answers. Then:
  80. 1. Open the installed folder as an **Obsidian vault**
  81. 2. Enable the **Obsidian CLI** in Settings β†’ General (requires Obsidian 1.12+)
  82. 3. Run your agent in the vault directory: **`claude`**, **`codex`**, or **`gemini`**. Codex runs the vault's hooks only once the folder is trusted and each hook approved: see [Using with Other Agents](#-using-with-other-agents).
  83. 4. Start talking about work
  84. [ShardMind](https://github.com/breferrari/shardmind) is the package manager for Obsidian vault templates. The install adds a `.shardmind/` sidecar that powers the wizard, optional modules (skip what you don't use), and three-way-merge upgrades. With every value at its default the install is byte-equivalent to `git clone` β€” clone-UX is preserved exactly. Delete `.shardmind/` and `shard-values.yaml` from the installed vault and it keeps working: ShardMind is additive, not load-bearing.
  85. ### Or clone directly
  86. ```bash
  87. git clone https://github.com/breferrari/obsidian-mind.git
  88. ```
  89. Or use it as a **GitHub template**. Skip the wizard, get the bare template. Then run through the same 4 steps above, plus fill in **`brain/North Star.md`** with your goals (the ShardMind wizard does this for you).
  90. ### πŸ” Recommended: QMD Semantic Search
  91. QMD is where most of the agent's retrieval intelligence comes from. Optional in the strict sense β€” the vault falls back to grep + the Obsidian CLI β€” but the experience is meaningfully better with it:
  92. - **Semantic recall.** Find "what did we decide about caching" even when the note is titled "Redis Migration ADR."
  93. - **Brain topics available on demand.** Your agent is instructed (via `AGENTS.md`, which points to `.claude/rules/brain-topics.md`) to consult `brain/` guidance through QMD when the conversation touches a listed topic.
  94. - **Subagents get sharper context.** `context-loader`, `review-prep`, `brag-spotter`, and friends consult QMD first, then fall back to grep.
  95. - **Native agent tools via MCP.** Registered as a [Model Context Protocol](https://modelcontextprotocol.io) server in `.mcp.json` β€” when QMD is installed, `mcp__qmd__query`, `mcp__qmd__get`, and `mcp__qmd__multi_get` appear in the agent's tool menu alongside Read and Edit. Subagents, slash commands, and the main conversation all call the same typed contract. Add another MCP-aware tool later (a database, a ticketing system, a calendar) and it plugs in the same way.
  96. ```bash
  97. npm install -g @tobilu/qmd
  98. node --experimental-strip-types .scripts/qmd-bootstrap.ts
  99. ```
  100. The bootstrap is idempotent β€” safe to re-run. It resolves this vault's index name β€” the `qmd_index` field from `vault-manifest.json` when set, otherwise the vault folder name slugified β€” reads `qmd_context`, registers the collection, attaches the context, and builds the index + embeddings. The SessionStart hook and `.mcp.json` wrapper both read the same manifest field, so CLI queries, the MCP server, and the re-index all scope to the same named SQLite store. This isolates the vault from any other QMD-using vault on the same machine.
  101. If you want to use a different index name (for example, one vault per engineer on a shared workstation), edit `qmd_index` in `vault-manifest.json` before running the bootstrap. Once the store is populated, always pass `--index <name>` to the CLI:
  102. ```bash
  103. qmd --index obsidian-mind query "what did we decide about caching"
  104. qmd --index obsidian-mind update # after bulk edits
  105. qmd --index obsidian-mind embed # after many new notes
  106. ```
  107. #### How it works under the hood
  108. QMD runs **three small models locally**, so there is no API key to set up, no per-query cost, and it works offline:
  109. | model | size | job |
  110. |---|---|---|
  111. | `embeddinggemma-300M` | ~328MB | turns notes and queries into vectors |
  112. | `qmd-query-expansion-1.7B` | ~1.28GB | rewrites your query into better search terms |
  113. | `Qwen3-Reranker-0.6B` | ~640MB | reorders the shortlist by actual relevance |
  114. They download on first use and are cached. QMD offloads to the GPU when it finds one β€” CUDA on a discrete card, Metal on Apple Silicon β€” and falls back to CPU otherwise. Check what yours is doing with `qmd doctor`.
  115. Use qmd 2.5.1 or later. In 2.1, `qmd status` probes the GPU, and on a machine without one that can take several seconds (4 to 37 s on CI runners, measured 2026-10-13, #349). SessionStart's self-heal reads `qmd status` under a 5-second limit, so a status that times out leaves it unable to see a broken install.
  116. The three CLI verbs map onto that stack, cheapest first: `qmd search` is BM25 keywords with **no model at all**, `qmd vsearch` is vector-only, and `qmd query` is the full hybrid. If you want to avoid the larger downloads, `search` alone is genuinely useful.
  117. #### What that means for the MCP server
  118. The `om` server sends a lexical *and* a vector sub-query, so retrieval finds the note that answers your question even when it shares no keywords with it. Practical consequences worth knowing:
  119. - **Reads are the expensive side, not writes.** A query embeds locally before it can search, so `recall` with a query takes a couple of seconds while `recall` without one is near-instant. `search` over notes is fast β€” it is the vector step that costs.
  120. - **Writing a memory does not wait for the model.** The index update is synchronous, so a new memory is immediately retrievable; generating its vector happens in the background, because that only affects where it *ranks*, not whether it is found.
  121. - **No index, no problem.** Without QMD the server falls back to lexical matching. Ordering gets worse; nothing disappears.
  122. > [!NOTE]
  123. > If QMD isn't installed, everything still works β€” the agent falls back to grep and the Obsidian CLI, and the MCP server entry is skipped with a harmless warning.
  124. ---
  125. ## πŸ“‹ Requirements
  126. - [Obsidian](https://obsidian.md) 1.12+ (for CLI support)
  127. - An AI coding agent: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (full support), [Codex CLI](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
  128. - [Node 22+ LTS](https://nodejs.org) (for hook scripts β€” typically already installed alongside Claude Code / Codex / Gemini CLI)
  129. - Git (for version history)
  130. - [QMD](https://github.com/tobi/qmd) (optional, for semantic search)
  131. > **Note on the Node flag.** Hook scripts execute TypeScript directly via Node's `--experimental-strip-types` flag, stable in Node 22.6+ (Aug 2024) and the default behaviour in Node 23.6+. The flag is marked experimental but has been unchanged across 22 LTS and 24 LTS; if a future Node release retires or renames it, hook commands in `.claude/settings.json`, `.codex/hooks.json`, and `.gemini/settings.json` need a one-line update.
  132. ---
  133. ## βš™οΈ How It Works
  134. **Procedural code owns the environment. The agent owns content.** The hooks in `.claude/scripts/` handle classification, validation, indexing, and lifecycle injection β€” deterministic, testable, runs the same for every agent. Writing notes, filing them, linking them, drafting briefs β€” those are judgments, and they stay with the agent. The two halves meet at small handoffs (hooks inject context, agent reads the vault) so neither has to do the other's job.
  135. **Folders group by purpose. Links group by meaning.** A note lives in one folder (its home) but links to many notes (its context). Your agent maintains this graph β€” linking work notes to people, decisions, and competencies automatically. When review season arrives, the backlinks on each competency note are already the evidence trail. A note without links is a bug.
  136. **Vault-first memory** keeps context across sessions and machines. All durable knowledge lives in `brain/` topic notes (git-tracked, Obsidian-browsable, linked). Claude Code's `MEMORY.md` (`~/.claude/`) is an auto-loaded index that points to vault locations β€” never the storage itself. This means memories survive machine changes and are part of the graph.
  137. **Sessions have a designed lifecycle.** The `SessionStart` hook auto-injects your North Star goals, active projects, recent changes, open tasks, and the full vault file listing β€” your agent starts every session with context, not a blank slate. At the end, say "wrap up" and the agent runs `/om-wrap-up` β€” verifying notes, updating indexes, and spotting uncaptured wins. The `AGENTS.md` operating manual governs everything in between: where to file things, how to link, when to split a note, what to do with decisions and incidents.
  138. ### πŸ”— Hooks
  139. The lifecycle hooks handle routing automatically:
  140. | Hook | When | What |
  141. |------|------|------|
  142. | πŸš€ SessionStart | On startup/resume | QMD re-index + self-heal, inject North Star focus, active work, recent changes, tasks, file listing, vault-hygiene drift flags β€” held under a byte budget that fits Claude Code's hook output cap, ending with an injection-size meter |
  143. | πŸ’¬ UserPromptSubmit | Every message | Classifies content (decision, incident, win, 1:1, architecture, person, project update) and injects routing hints; also hands the agent the Stop report from the previous turn |
  144. | ✍️ PostToolUse | After writing `.md` | Validates frontmatter + wikilinks, blocks misplaced memory files, flags oversized notes (split, don't trim) and write-time topic clusters |
  145. | πŸ’Ύ PreCompact | Before context compaction | Backs up session transcript to `thinking/session-logs/` |
  146. | 🏁 Stop | After every response | Checklist + concrete drift findings (same hygiene scan as SessionStart), shown once per session and again only when they change: you see a short summary, one line per section, and the agent gets the full report with your next message and decides whether to act; hands drift to `om-tidy` |
  147. > [!TIP]
  148. > You just talk. The hooks handle the routing.
  149. ### 🧩 The Claude Code mod
  150. On Claude Code 2.1.287 or later, the vault also ships a mod: `.claude/skills/obsidian-mind/`, a plugin whose code runs inside Claude Code. It runs the vault's own hook scripts and changes only how their output reaches the session:
  151. - **Session context arrives as an instruction file**, the way `AGENTS.md` does. It is re-read whole after compaction and `/clear` (as hook output it shrinks to a pointer), it reaches general-purpose subagents (hook output never does), and it is not cut at Claude Code's 10,000-character hook limit. Its budget is `eager_layer_instruction_budget_bytes` in `vault-manifest.json`; sections that never shrink, such as open tasks, can still take it past that. `/memory` lists it as `.claude/session-context.md`.
  152. - **The Stop report becomes one line under the answer.** When the findings change you see a line beneath Claude's reply, starting with the mod's name β€” `obsidian-mind: vault check: …`. Claude Code joins the names of the plugins that answered on Stop with `+`, so when another plugin also answers, the label reads `obsidian-mind+<plugin>: vault check: …`. Claude gets the full report with your next message, unseen. A finding marked urgent gets Claude's attention at once instead, once per message you send (a second one waits inside the report); the template's own report has none.
  153. For each event it handles, the mod tells the matching hook to stand down. Wherever the mod does not load, the hooks run exactly as before: Codex and Gemini, older Claude Code, a session started in a vault subfolder (launch from the vault root, or `/cd` there and `/clear`), or a folder you have not trusted. It loads only after you accept Claude Code's trust prompt for the vault.
  154. A mod is unsandboxed code that runs with your permissions, so check what it does before trusting the folder: `claude plugin validate .claude/skills/obsidian-mind` lists every event it hooks and every call it makes (it runs the vault's own scripts, writes the context file, remembers in its own store which report each session was shown, and can submit a prompt for an urgent finding, nothing else). To turn it off, add `"enabledPlugins": { "obsidian-mind@skills-dir": false }` to `.claude/settings.local.json`.
  155. <!-- mod-validate:start -->
  156. The two lines that matter in its output, for this version of the mod:
  157. ```text
  158. ❯ ./register.ts hooks: classic.SessionStart, prompt.context, classic.Stop, turn.complete, prompt.submit, turn.start
  159. ❯ ./register.ts calls: $.fs.write, $.process.run (via runScript), $.prompt.submit, $.session.root, $.state.get, $.state.set, $.store.get (via setShown, shownFor), $.store.set (via setShown), $.ui.invalidate
  160. ```
  161. <!-- mod-validate:end -->
  162. ### ⚑ Token Efficiency
  163. obsidian-mind does **not** dump your entire vault into context. It uses tiered loading to keep token costs low:
  164. | Tier | What | When | Cost |
  165. |------|------|------|------|
  166. | **Always** | `AGENTS.md` (plus `.claude/rules/` on Claude Code) + SessionStart context (North Star excerpt, git summary, tasks, vault file listing) | Session start | capped by the manifest budget, itself held under Claude Code's 10,000-character hook output cap; the meter reports the real size every session |
  167. | **On-demand** | QMD semantic search results | When the agent needs specific context | Targeted |
  168. | **Triggered** | Classification routing hints | Every message | ~100 tokens |
  169. | **Triggered** | PostToolUse validation | After `.md` writes | ~200 tokens |
  170. | **Rare** | Full file reads | Only when explicitly needed | Variable |
  171. SessionStart loads **lightweight context** β€” small excerpts from key files, filenames, and git summary β€” not full note contents. Five mechanisms keep the eager layer honest as the vault grows: **source-aware injection** (resume/compact re-inject only volatile sections β€” the static bulk is already in-conversation), an **injection-size meter** as the last line of every injection (you always see what context costs), an **injection budget** that enforces what the meter measures (over the ceiling, the cheapest-to-lose sections degrade to pointers β€” and the meter names every one it dropped, because a silent loss is worse than the bloat), a **single hook spawn per write** (the QMD refresh rides the validation hook), and **listing collapse** (any folder past a note-count threshold folds to one count line, so a vault can't outgrow the ceiling through whichever folder nobody thought to configure). Both the budget and the threshold are tunable in `vault-manifest.json`, and the budget is held under Claude Code's 10,000-character hook output cap whatever it is set to, because past the cap a session receives only a 2,000-character preview. The agent queries by meaning via QMD before reading files, so it pulls only what's relevant. The classification hook is one lightweight Node call per message. The validation hook only fires on markdown writes and skips excluded paths.
  172. ### 🌐 Using with Other Agents
  173. obsidian-mind works with Claude Code, Codex CLI, Gemini CLI, Antigravity and Grok. Every agent reads one instruction file, `AGENTS.md`. The hook scripts in `.claude/scripts/` and the commands in `.claude/commands/` are agent-agnostic β€” pure Markdown, TypeScript, and shell with no SDK dependencies. `.claude/rules/` holds guidance only Claude Code can use (its skills, subagents, auto-memory index, hooks and mod), and the sections `AGENTS.md` moved out to stay under its size cap. Claude Code and Grok load every file there at session start, so Claude keeps the whole manual; the other agents read a moved section when `AGENTS.md` points them to it.
  174. | Agent | Reads `AGENTS.md` | From a vault subfolder | Also loads | Known gaps |
  175. |---|---|---|---|---|
  176. | **Claude Code** | Natively, when no `CLAUDE.md` is present | Yes, but `@` imports are dropped (upstream) | `.claude/rules/*.md` | A `CLAUDE.md` beside or above `AGENTS.md` is read instead, silently: see [Troubleshooting](#-troubleshooting) |
  177. | **Codex CLI** | Natively | Yes (walks up to the git root) | β€” | Stops reading past ~32 KiB, silently |
  178. | **Gemini CLI** | Through `.gemini/settings.json` (`context.fileName`) | **No**: see [Troubleshooting](#-troubleshooting) | β€” | What a live session does with it is not yet observed (TBC) |
  179. | **Antigravity** | Natively | Yes | β€” (not `.claude/rules/`, not `CLAUDE.md`) | Stops reading past ~24,000 bytes, silently. Has a workspace-trust dialog; whether it gates `AGENTS.md` is TBC (a headless `-p` run loaded it in a never-opened folder). Its `.agents/` manifests are not exercised here (TBC) |
  180. | **Grok** | Once the folder is trusted | Yes, once trusted | `.claude/rules/*.md` and `CLAUDE.md`, plus project `.claude/settings.json` hooks and user-level `~/.claude` skills, permissions and hooks | An untrusted folder gets no project instructions at all: see [Troubleshooting](#-troubleshooting) |
  181. Observed with scratch vaults as of 2026-10-06 (Claude Code 2.1.291, Codex CLI 0.160.0, Gemini CLI 0.37.1 discovery log, Antigravity 1.3.0, Grok 1.0.46); the measurements are in [#321](https://github.com/breferrari/obsidian-mind/issues/321). A test keeps `AGENTS.md` under 22,000 bytes, so no agent cuts it off.
  182. **Claude Code** β€” full support. Hooks, commands, subagents, and the memory system all work out of the box.
  183. **Codex CLI** β€” hook config at `.codex/hooks.json` wires the same hook scripts Claude Code uses β€” session context, message classification, and write validation work automatically. Commands work as regular prompts (e.g. type `om-standup` without the `/` prefix).
  184. Codex runs a project's hooks only once two kinds of trust are in place (observed with Codex CLI 0.160.0 as of 2026-10-13, [#345](https://github.com/breferrari/obsidian-mind/issues/345)):
  185. - **The vault folder is trusted.** Codex records this in `~/.codex/config.toml` under `[projects.'<path>']`. On Windows the key is the `\\?\`-prefixed path, e.g. `[projects.'\\?\C:\path\to\vault']`.
  186. - **Each hook is approved.** Codex stores each approval as a `trusted_hash` under `[hooks.state]`. Approving them in an interactive `codex` session is expected to write these (inferred: the #345 check stood in for them with `--dangerously-bypass-hook-trust`, a flag for one non-interactive run).
  187. Until both are in place, Codex runs no hook, and the session gets no vault context.
  188. **Gemini CLI** β€” hook config at `.gemini/settings.json` maps Gemini's event names to the shared hook scripts, and its `context.fileName` setting points Gemini at `AGENTS.md`. Gemini reads custom commands only as TOML, so `.gemini/commands/` holds a generated wrapper per command that injects the command's `.md` (`node --experimental-strip-types .scripts/gemini-commands.ts` regenerates them).
  189. **Antigravity** and **Grok** β€” read `AGENTS.md` for vault conventions. Their hook, skill and command layers are tracked in [#322](https://github.com/breferrari/obsidian-mind/issues/322) and [#323](https://github.com/breferrari/obsidian-mind/issues/323).
  190. **Other agents** (Cursor, Windsurf, GitHub Copilot, JetBrains AI) β€” read `AGENTS.md` for vault conventions. Hook support varies by agent.
  191. > [!NOTE]
  192. > Hooks, commands, subagent prompts, and vault memory (`brain/`) are all agent-agnostic. Only the `~/.claude/` auto-memory loader and the `obsidian-mind` mod are Claude Code-specific. `.claude/rules/hooks-per-agent.md` maps each hook to each agent's event.
  193. ---
  194. ## 🧠 Reach Your Vault From Any Repo
  195. Your vault normally only helps while you are sitting in it. The **`om` MCP server** changes that: a coding session in *any other repository* can search your notes, read them, follow the graph, and record what it learned back into the vault.
  196. ### Step 1 β€” register the server once, for every repo
  197. ```bash
  198. claude mcp add --scope user om node "/absolute/path/to/your-vault/.claude/scripts/om-mcp.mjs"
  199. ```
  200. User scope is the right default here: it registers in your own config, so the server is available in **every directory on the machine** with nothing added to any repository. No env var is needed either, because the launcher resolves the vault from its own location.
  201. <details>
  202. <summary>Per-repo alternative, and one trap to avoid</summary>
  203. If you would rather a specific repo carry the wiring (so a teammate gets it on clone), put it in that project's `.mcp.json`:
  204. ```json
  205. {
  206. "mcpServers": {
  207. "om": {
  208. "command": "node",
  209. "args": ["/absolute/path/to/your-vault/.claude/scripts/om-mcp.mjs"]
  210. }
  211. }
  212. }
  213. ```
  214. Note the cost: that path is **absolute and machine-specific**, so committing it breaks every collaborator and every other machine of yours.
  215. **Use an absolute path, and do not copy the relative one.** This vault's own `.mcp.json` registers `qmd` with a *relative* path (`.claude/scripts/qmd-mcp.mjs`). That is correct there, because a relative path resolves against the current working directory and a session in the vault is already in it. Reused for `om` in a consuming project, the same shape silently resolves against *that* project instead, and the server never starts.
  216. </details>
  217. ### Step 2 β€” point the consuming project at the vault
  218. Add this to that project's own instruction file (`CLAUDE.md` or `AGENTS.md`), filling in the triggers:
  219. ```markdown
  220. ## Where design decisions live
  221. Design rationale for this project is recorded outside this repo, reachable
  222. through the `om` MCP server.
  223. - **`search`** reaches the written record: why a choice was made, what was
  224. rejected, what a constraint was set against. **Start here.**
  225. - **`expand`** shows a known note's links and backlinks, which is cheaper than
  226. searching again for its neighbourhood.
  227. - **`recall`** returns short durable lessons scoped to this project. It is empty
  228. until sessions put things in it, so early on it returns nothing, and that is
  229. *not* evidence the record is missing.
  230. - **`health`** when something that should be there cannot be found. Every failure
  231. in this layer looks identical from outside (no results), and this tells them
  232. apart.
  233. Consult the record before changing:
  234. - <the storage format or schema>
  235. - <the ID or key semantics>
  236. - <the public surface: CLI flags, API shape, exported names>
  237. If that record and this repo disagree, the record holds the *why*. Reconcile
  238. before changing behaviour.
  239. **Say what came back, in whatever you write before implementing:** a plan, a
  240. design note, an issue comment. Name the recorded decisions the work rests on,
  241. anything you found that argues *against* the approach, and an explicit "nothing
  242. recorded on this" when the record is empty, which is a finding rather than a
  243. blank to skip. Consulting once at the start of a task is consulting at the
  244. moment you know least about what you will need; writing the result down moves it
  245. to the moment you commit, while a contradiction is still free to fix.
  246. ## Recording what you learn
  247. Two tools, and picking the wrong one is the common mistake. The test is whether
  248. it would help someone working on a **different** project.
  249. - **`remember`** stores a durable lesson: a constraint you discovered, a gotcha
  250. that cost time, a rule that generalises. Set `confidence`
  251. (`verified` / `inferred` / `unverified`) honestly and supply `verification`
  252. when you claim `verified`. For something specific to this project use
  253. `scope: "project"` with `projects: ["<this-repo>"]`. Reach for
  254. `scope: "platform"` before `"general"`: a dependency's quirk or a language's
  255. rule is platform-level however hard-won, and `general` claims it would help
  256. someone whose stack shares nothing with yours. When you do claim `general`,
  257. supply `generality` saying why, the same way `verification` backs `verified`.
  258. - **`record_work`** files what happened *here*: changes, decisions and the
  259. alternatives rejected, what was learned, what is still open, how it was
  260. verified.
  261. A dependency limitation that would bite any project is a `remember`. "Landed the
  262. watch engine and here is what it cost" is a `record_work`. Do both when both are
  263. true.
  264. ```
  265. **Three to five triggers, and name specific nouns.** `Consult it before changing the storage format, ID semantics, or the CLI surface` works. `Check the vault for context` is exactly the advisory phrasing that gets skipped, because it gives the model nothing to match against the task in front of it.
  266. **Anchor the consultation to an artifact, not to a moment.** "Consult before changing X" fires once, at the start of a task, which is when the session knows least about what it will need. Requiring the *result* to appear in whatever the project writes before implementing turns consultation from something a session intends to do into something an artifact is incomplete without. Measured across a day of real use: captures ran roughly four times heavier than consultations, because `remember` fires on an **event** (you just learned something) while consulting fires on **intention**. Event-triggered behaviour happens; intention-triggered behaviour decays.
  267. > [!TIP]
  268. > **Do not lead with `recall`.** It returns *memories*, and the store is empty on a project's first session **by construction**: `remember` refuses when called from inside the vault, since a memory written there would be scoped to the vault and reach nobody. So memories only ever arrive from outside. A snippet that promises `recall` will return this project's decisions therefore returns nothing on the first run, and fails **silently as "no results"** rather than as an error.
  269. > [!IMPORTANT]
  270. > **Both steps are required, and the second is not paperwork.** Measured: with the server wired and no repo-side instruction, a session made **zero** vault calls and implemented a design the vault had recorded as explicitly rejected. With the instruction present, it refused and cited the note.
  271. >
  272. > A **prohibition** in the MCP `instructions` field propagates into the calling session reliably. A positive *"go consult the vault"* is advisory and gets skipped whenever a nearer source exists. The server can stop a session doing something; only the project's own law makes one go looking.
  273. >
  274. > That asymmetry decides *which side* a rule belongs on, and it matters most for anything you would rather not advertise. Writing "this repo deliberately excludes X" into a **public** repo announces the withholding and points at exactly what is being withheld. The same rule as a prohibition in `instructions` reaches every session invisibly, and the repo says nothing at all. Routing belongs repo-side because it has to; constraints belong server-side because they can.
  275. **What the session gets:** `search` (semantic + keyword), `expand` (a note's links and backlinks), `recall` (durable lessons scoped to that repo), `remember` (record a lesson), `record_work` (file what happened), `reason` (judgement across several notes), and `health` (is the wiring intact?). Plus your notes as readable resources.
  276. **`reason` is the one that thinks.** The others retrieve; this one reads the vault with a second Claude session and answers questions that need judgement across notes β€” *is what I am about to do consistent with what these six notes decided?* It seeds itself from search, so you never have to search first. It runs on your own CLI default model, so the vault answers at the level you are already working at, and nothing about it is capped: it is Claude, on your machine, under your auth. Every call is logged with its cost, turns, model and wall time. Its answers are marked `confidence: inferred` and are never recorded as memories on their own β€” your session decides whether any of it is worth keeping.
  277. **Repos are identified by folder name**, which is right until it isn't β€” two repos both called `api` share one identity and therefore each other's memories. Drop a `.om-project` file with a distinct name at the repo root to separate them; `health` tells you which repo it thinks is calling and where that name came from.
  278. **Cross-repo memory with an epistemic contract.** A lesson learned in one repo reaches the repos it was scoped to and no others. Reach is *declared at write time*, never guessed at read time, so a sibling project does not inherit another's constraints. Everything recorded carries `confidence: verified | inferred | unverified`, dated volatile facts, and provenance derived server-side β€” a session cannot claim to be a project it is not. Corrections supersede rather than overwrite, so the store gets *more* trustworthy as it grows instead of accumulating contradictions.
  279. **Which notes it serves.** Your vault, your notes, your session β€” the default is simply what your vault already declares as your content (`user_content_roots`), at the granularity you wrote it (`work/active/`, not all of `work/`). Set `mcp_exposed_roots` in `vault-manifest.json` only if this vault holds material that is **not yours to share** β€” employer-confidential notes, a client's data. A note tagged `private` is never served, and memories are never served as ordinary notes, since they carry their own scope. One case reads across the two: when a capture's `promoted:` marker carries an anchor, `recall` serves that block out of `brain/` so a foreign repo gets the corrected version rather than the capture as first written β€” bounded by this same policy, so a `private` or withheld note is refused there too.
  280. Every read is logged with the calling repo, so "what did that session actually see" is answerable afterwards.
  281. > [!NOTE]
  282. > Keeping vault material out of a public PR is the **contract's** job, not the exposure list's β€” a session can read your vault directly regardless. The prohibition injected into the calling session is the part that measurably holds.
  283. **Want the mechanics?** `ARCHITECTURE.md` β†’ *Reaching the Vault From Another Repo* walks the whole layer with diagrams: the four MCP surfaces and why the non-tool ones matter, the identity handshake, a `search` call traced end to end, how each memory's reach is evaluated, the write path, and every failure mode against the signal that reveals it.
  284. ---
  285. ## πŸ“… Daily Workflow
  286. **Morning**: Run `/om-standup`. Your agent loads your North Star, active projects, open tasks, and recent changes. You get a structured summary and suggested priorities.
  287. **Throughout the day**: Talk naturally. Mention a decision you made, an incident that happened, a 1:1 you just had, a win you want to remember. The classification hook nudges the agent to file each piece correctly. For bigger brain dumps, use `/om-dump` and narrate everything at once.
  288. **End of day**: Say "wrap up" and the agent invokes `/om-wrap-up` β€” verifies notes, updates indexes, checks links, spots uncaptured wins.
  289. **Weekly**: Run `/om-weekly` for cross-session synthesis β€” North Star alignment, patterns, uncaptured wins, and next-week priorities. Run `/om-vault-audit` to catch orphan notes, broken links, and stale content.
  290. **Review season**: Run `/om-review-brief manager` and get a structured review prep document with all the evidence already linked.
  291. ---
  292. ## πŸ› οΈ Commands
  293. Defined in `.claude/commands/`. Run them in Claude Code, Codex CLI, or Gemini CLI.
  294. | Command | What It Does |
  295. |---------|-------------|
  296. | `/om-standup` | Morning kickoff β€” loads context, reviews yesterday, surfaces tasks, suggests priorities |
  297. | `/om-dump` | Freeform capture β€” talk naturally about anything, routes it all to the right notes |
  298. | `/om-wrap-up` | Full session review β€” verify notes, indexes, links, suggest improvements |
  299. | `/om-humanize` | Voice-calibrated editing β€” makes Claude-drafted text sound like you wrote it |
  300. | `/om-weekly` | Weekly synthesis β€” cross-session patterns, North Star alignment, uncaptured wins |
  301. | `/om-capture-1on1` | Capture a 1:1 meeting transcript into a structured vault note |
  302. | `/om-incident-capture` | Capture an incident from Slack/channels into structured notes |
  303. | `/om-slack-scan` | Deep scan Slack channels/DMs for evidence |
  304. | `/om-peer-scan` | Deep scan a peer's GitHub PRs for review prep |
  305. | `/om-review-brief` | Generate a review brief (manager or peer version) |
  306. | `/om-self-review` | Write your self-assessment for review season β€” projects, competencies, principles |
  307. | `/om-review-peer` | Write a peer review β€” projects, principles, performance summary |
  308. | `/om-tidy` | Self-maintenance β€” acts on every hygiene flag: archive, group, split. Never deletes, never commits |
  309. | `/om-correct` | Sweep a corrected fact β€” applies it at the single source, links restatements, preserves dated records |
  310. | `/om-vault-audit` | Audit indexes, links, orphans, stale context |
  311. | `/om-vault-upgrade` | Upgrade this vault through ShardMind (keeps your local improvements), or import content from an existing vault β€” version detection, classification, migration |
  312. | `/om-prep-1on1` | Prep for an upcoming 1:1 β€” load person context, open items, suggested agenda |
  313. | `/om-meeting` | Prep for any meeting by topic β€” subject-forward briefing with open items and considerations |
  314. | `/om-intake` | Process meeting notes inbox β€” classify and route to the right vault notes |
  315. | `/om-project-archive` | Move a completed project from active/ to archive/, update indexes |
  316. ---
  317. ## πŸ€– Subagents
  318. Specialized agents that run in isolated context windows. They handle heavy operations without polluting your main conversation.
  319. | Agent | Purpose | Invoked by |
  320. |-------|---------|------------|
  321. | `brag-spotter` | Finds uncaptured wins and competency gaps | `/om-wrap-up`, `/om-weekly` |
  322. | `context-loader` | Loads all vault context about a person, project, or concept | Direct |
  323. | `cross-linker` | Finds missing wikilinks, orphans, broken backlinks | `/om-vault-audit` |
  324. | `people-profiler` | Bulk creates/updates person notes from Slack profiles | `/om-incident-capture` |
  325. | `review-prep` | Aggregates all performance evidence for a review period | `/om-review-brief` |
  326. | `slack-archaeologist` | Full Slack reconstruction β€” every message, thread, profile | `/om-incident-capture` |
  327. | `vault-librarian` | Deep vault maintenance β€” orphans, broken links, stale notes | `/om-vault-audit` |
  328. | `review-fact-checker` | Verify every claim in a review draft against vault sources | `/om-self-review`, `/om-review-peer` |
  329. | `vault-migrator` | Classify, transform, and migrate content from a source vault | `/om-vault-upgrade` |
  330. > [!NOTE]
  331. > Subagents are defined in `.claude/agents/`. You can add your own for domain-specific workflows.
  332. ---
  333. ## πŸ“Š Performance Graph
  334. The vault doubles as a performance tracking system:
  335. 1. **Competency notes** in `perf/competencies/` define your org's competency framework β€” one note per competency
  336. 2. **Work notes** link to competencies in their `## Related` section, annotated with what was demonstrated
  337. 3. **Backlinks accumulate automatically** β€” review prep becomes reading the backlinks panel on each competency note
  338. 4. **Brag Doc** aggregates wins per quarter with links to evidence notes
  339. 5. **`/om-peer-scan`** deep-scans a colleague's GitHub PRs and writes structured evidence to `perf/evidence/`
  340. 6. **`/om-review-brief`** generates a full review brief by aggregating everything: brag entries, decisions, incidents, competency evidence, and 1:1 feedback
  341. > [!TIP]
  342. > To get started: create competency notes from the template, then link your work notes to them as you go. The graph does the rest.
  343. ---
  344. ## πŸ“‹ Bases
  345. The `bases/` folder contains database views that query your notes' frontmatter properties. They update automatically as notes change.
  346. | Base | Shows |
  347. |------|-------|
  348. | Work Dashboard | Active projects filtered by quarter, grouped by status β€” plus a Stale Actives view (active but untouched 14+ days) |
  349. | Recently Touched | Every note by real modified time β€” the correct answer to "what did I work on recently" (filename dates lie for living notes) |
  350. | Incidents | All incidents sorted by severity and date |
  351. | People Directory | Everyone in `org/people/` with role, team |
  352. | 1:1 History | All 1:1 notes sortable by person and date |
  353. | Review Evidence | PR scans and evidence grouped by person and cycle |
  354. | Competency Map | Competencies with evidence counts from backlinks |
  355. | Templates | Quick access to all templates |
  356. `Home.md` embeds these views, making it the vault's dashboard.
  357. ---
  358. ## πŸ“ Vault Structure
  359. ```
  360. Home.md Vault entry point β€” embedded Base views, quick links
  361. AGENTS.md Operating manual β€” read by every agent, every session
  362. vault-manifest.json Template metadata β€” version, structure, schemas
  363. .shardmindignore Files excluded from `shardmind install` (CONTRIBUTING, translations, marketing media)
  364. CHANGELOG.md Version history
  365. CONTRIBUTING.md Template development checklist
  366. README.md Product documentation
  367. LICENSE MIT license
  368. bases/ Dynamic database views (Work Dashboard, Incidents, People, etc.)
  369. work/
  370. active/ Current projects (1–3 files at a time)
  371. archive/YYYY/ Completed work, organized by year
  372. incidents/ Incident docs (main note + RCA + deep dive)
  373. 1-1/ 1:1 meeting notes β€” named <Person> YYYY-MM-DD.md
  374. Index.md Map of Content for all work
  375. org/
  376. people/ One note per person β€” role, team, relationship, key moments
  377. teams/ One note per team β€” members, scope, interactions
  378. People & Context.md MOC for organizational knowledge
  379. perf/
  380. Brag Doc.md Running log of wins, linked to evidence
  381. brag/ Quarterly brag notes (one per quarter)
  382. competencies/ One note per competency (link targets)
  383. evidence/ PR deep scans, data extracts for reviews
  384. <cycle>/ Review cycle briefs and artifacts
  385. brain/
  386. North Star.md Goals and focus areas β€” read every session
  387. Memories.md Index of memory topics
  388. Key Decisions.md Significant decisions and their reasoning
  389. Patterns.md Recurring patterns observed across work
  390. Gotchas.md Things that have gone wrong and why
  391. Skills.md Custom workflows and slash commands
  392. reference/ Codebase knowledge, architecture maps, flow docs
  393. thinking/ Scratchpad for drafts β€” promote findings, then delete
  394. templates/ Obsidian templates with YAML frontmatter
  395. .claude/
  396. rules/ Claude Code-only guidance, loaded beside AGENTS.md
  397. commands/ 20 slash commands
  398. agents/ 10 subagents
  399. scripts/ Hook scripts + charcount.ts utility
  400. skills/ Obsidian + QMD skills, and the obsidian-mind mod
  401. settings.json 5 hooks configuration
  402. .scripts/ Vault-level tooling β€” QMD bootstrap (run once on a fresh clone)
  403. .shardmind/ ShardMind sidecar β€” only used if installed via `shardmind install`
  404. shard.yaml Manifest (name, version, modules, hooks)
  405. shard-schema.yaml Wizard values + module gating
  406. hooks/ bootstrap (git init + QMD), personalize (North Star), post-update
  407. ```
  408. > [!NOTE]
  409. > `.shardmind/` is **additive, not load-bearing.** A clone-and-open vault never reads it; only the `shardmind` CLI does. Delete it and the vault keeps working. See the v6 layout contract in [shardmind/docs/SHARD-LAYOUT.md](https://github.com/breferrari/shardmind/blob/main/docs/SHARD-LAYOUT.md).
  410. ---
  411. ## πŸ“ Templates
  412. Templates with YAML frontmatter, each including a `description` field for progressive disclosure:
  413. - **Work Note** β€” date, description, project, status, quarter, tags
  414. - **Decision Record** β€” date, description, status (proposed/accepted/deprecated), owner, context
  415. - **Thinking Note** β€” date, description, context, tags (scratchpad β€” delete after promoting)
  416. - **Competency Note** β€” date, description, current-level, target-level, proficiency table
  417. - **1:1 Note** β€” date, person, key takeaways, action items, quotes
  418. - **Incident Note** β€” date, ticket, severity, role, timeline, root cause, impact
  419. ---
  420. ## πŸ”§ What's Included
  421. ### 🧩 Obsidian Skills
  422. [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) pre-installed in `.claude/skills/`:
  423. - **obsidian-markdown** β€” Obsidian-flavored markdown (wikilinks, embeds, callouts, properties)
  424. - **obsidian-cli** β€” CLI commands for vault operations
  425. - **obsidian-bases** β€” Database-style `.base` files
  426. - **json-canvas** β€” Visual `.canvas` file creation
  427. - **defuddle** β€” Web page to markdown extraction
  428. ### πŸ” QMD Skill
  429. A custom skill in `.claude/skills/qmd/` that teaches the agent to use [QMD](https://github.com/tobi/qmd) semantic search proactively β€” before reading files, before creating notes (to check for duplicates), and after creating notes (to find related content that should link to it).
  430. ---
  431. ## 🎨 Customize It
  432. This is a starting point. Adapt it to how you work:
  433. | What | Where |
  434. |------|-------|
  435. | Your goals | `brain/North Star.md` β€” grounds every session |
  436. | Your org | `org/` β€” add your manager, team, key collaborators |
  437. | Your competencies | `perf/competencies/` β€” match your org's framework |
  438. | Your tools | `.claude/commands/` β€” edit for your GitHub org, Slack workspace |
  439. | Your conventions | `AGENTS.md` β€” the operating manual, evolve it as you go (`.claude/rules/` for Claude Code-only additions) |
  440. | Your domain | Add folders, subagents in `.claude/agents/`, or classification rules in `.claude/scripts/` |
  441. > [!IMPORTANT]
  442. > `AGENTS.md` is the operating manual. When you change conventions, update it β€” your agent reads it every session.
  443. ---
  444. ## πŸ”„ Upgrading
  445. ### Ask your agent
  446. The easiest way β€” just tell your agent:
  447. ```
  448. Update this vault to the latest obsidian-mind from https://github.com/breferrari/obsidian-mind
  449. ```
  450. The agent will pull the latest changes, resolve conflicts, and update infrastructure files. Works with Claude Code, Codex CLI, or Gemini CLI.
  451. ### Updating an existing clone
  452. If you cloned the repo directly:
  453. ```bash
  454. cd your-vault
  455. git pull origin main
  456. ```
  457. New files appear automatically and hook scripts are updated in place. If you edited `CLAUDE.md`, the pull stops on it, because you changed a file the template deleted: move your additions out as [Troubleshooting](#-troubleshooting) describes, then delete it.
  458. ### Updating a fork
  459. If you forked the repo:
  460. ```bash
  461. git remote add upstream https://github.com/breferrari/obsidian-mind.git
  462. git fetch upstream
  463. git merge upstream/main
  464. ```
  465. Resolve any conflicts in files you customized (typically `AGENTS.md`, `brain/` notes; a `CLAUDE.md` you edited conflicts with its deletion, see [Troubleshooting](#-troubleshooting)). Infrastructure files (`.claude/scripts/`, `.codex/`, `.gemini/`) should merge cleanly.
  466. ### Adopting an existing clone into ShardMind (v5.x β†’ v6)
  467. Already cloned obsidian-mind and want the wizard, optional modules, and three-way-merge upgrades without losing your customizations? `shardmind adopt` reconciles your existing vault into a managed v6 install β€” keeping every byte of your edits and only adding the `.shardmind/` sidecar + `shard-values.yaml`:
  468. ```bash
  469. npm install -g shardmind
  470. shardmind adopt github:breferrari/obsidian-mind
  471. ```
  472. The 2-way diff UI walks you through any local changes, asks per-file what to keep, then writes the engine metadata. Result: a v6-managed vault with your existing content intact, ready for `shardmind update` from there forward. No re-cloning.
  473. ### Migrating from an older vault (or any other vault)
  474. Using a pre-v5 obsidian-mind, or migrating from a totally different Obsidian vault? The `/om-vault-upgrade` command migrates your content into the latest template:
  475. ```bash
  476. # 1. Clone the latest obsidian-mind
  477. git clone https://github.com/breferrari/obsidian-mind.git ~/new-vault
  478. # 2. Open it in your agent
  479. cd ~/new-vault && claude # or codex, or gemini
  480. # 3. Run the upgrade pointing to your old vault
  481. /om-vault-upgrade ~/my-old-vault
  482. ```
  483. The agent will:
  484. 1. **Detect** your vault version (v1–v3.x, or identify it as a non-obsidian-mind vault)
  485. 2. **Inventory** every file β€” classify as user content, scaffold, infrastructure, or uncategorized
  486. 3. **Present a migration plan** β€” you see exactly what will be copied, transformed, and skipped
  487. 4. **Execute** after your approval β€” transforms frontmatter, fixes wikilinks, rebuilds indexes
  488. 5. **Validate** β€” checks for orphans, broken links, missing frontmatter
  489. Your old vault is **never modified**. Use `--dry-run` to preview the plan without executing.
  490. > [!NOTE]
  491. > Works with any Obsidian vault, not just obsidian-mind. For non-obsidian-mind vaults, the agent reads each note and classifies it semantically β€” routing work notes, people, incidents, 1:1s, and decisions to the right folders.
  492. ---
  493. ## 🩺 Troubleshooting
  494. **Claude Code ignores the vault's conventions.** Claude Code reads a `CLAUDE.md` in place of `AGENTS.md` and skips `AGENTS.md` without saying so. Two ways that happens:
  495. - **A leftover `CLAUDE.md` in the vault.** An update keeps a `CLAUDE.md` you edited. The session hygiene flags say `CLAUDE.md present beside AGENTS.md`, and `/om-vault-upgrade` lists it under **Move out**. Move what you added to `.claude/rules/local.md` (or into `AGENTS.md` if every agent needs it, keeping `AGENTS.md` under 23 KB, where the hygiene flags start: Antigravity stops reading it at ~24,000 bytes), then delete `CLAUDE.md`. Nothing is merged automatically.
  496. - **A `CLAUDE.md` in a folder above the vault.** Claude Code reads that one too, and `AGENTS.md` is skipped. The hygiene flag cannot see it, because it checks the vault root only. Move the vault out from under that folder, or move that file's content somewhere it applies only where you want it.
  497. **Gemini CLI loads no instructions when started in a vault subfolder.** Gemini's context search walks up the folders, but its settings lookup does not, so a session started in a subfolder never reads the vault's `.gemini/settings.json` and never learns to look for `AGENTS.md`. Start Gemini from the vault root.
  498. **Gemini ignores what you added to `GEMINI.md`.** Gemini now reads `AGENTS.md` (through `.gemini/settings.json`), so a leftover `GEMINI.md` is never loaded. The hygiene flags say `GEMINI.md present beside AGENTS.md`, and `/om-vault-upgrade` lists it under **Move out**. Move your additions to `AGENTS.md`, then delete it.
  499. **Grok reads nothing from the vault.** Grok loads project instructions only from a trusted folder. Trust the vault once: run `/hooks-trust` in a Grok session, or launch with `--trust`. One grant covers MCP, LSP, hooks, project instructions and project skills.
  500. ---
  501. ## πŸ—ΊοΈ Roadmap
  502. **Issues and bug reports welcome.** Code contributions go through assignment: comment on an issue to ask for it, and open a PR once it's assigned to you. A PR for an issue not assigned to you is closed without review. See [CONTRIBUTING.md](CONTRIBUTING.md).
  503. ---
  504. ## πŸ™ Design Influences
  505. - [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) β€” Official Obsidian agent skills
  506. - [James Bedford](https://x.com/jameesy) β€” Vault structure philosophy, separation of AI-generated content
  507. - [arscontexta](https://github.com/agenticnotetaking/arscontexta) β€” Progressive disclosure via description fields, session hooks
  508. ---
  509. ## πŸ‘€ Author
  510. Created by **[Brenno Ferrari](https://brennoferrari.com)** β€” Senior iOS Engineer in Berlin, building developer tools with Claude Code.
  511. ---
  512. ## πŸ“„ License
  513. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.