An agent-native backend for Obsidian. Give Claude Code or Codex a vault they can actually search, write into, and keep consistent, instead of a folder they grep blindly.
Obsidian is built for humans reading notes. Agents read differently: they need retrieval that works on a plain question, a place to put what they learn, and rules about what not to touch. ObsidAgent is the layer that supplies all three. It is a note graph backend, a hybrid search engine, and a set of skills that teach an agent the difference between a fact and an opinion in your own vault.
Works on any folder of markdown. No Obsidian plugin, no server, no account, no telemetry.
| Hybrid retrieval | BM25 fused with local embeddings. Ask what did I decide about pricing and get the note, even when it shares no keyword with your query. Ask CGSSetWindowShape and get the exact symbol. Neither ranker can do the other's job. |
| A real note graph | Wikilinks are the only structure. A reindex rebuilds every index from frontmatter, and reports what it will not guess at: dangling links, orphans, notes adrift from any index. |
| Write-back discipline | Skills that decide whether a finding belongs in a dated pass, a standing topic note, or nowhere. Writing nothing is a first-class outcome. |
| Graph-derived colour | Every note gets a hue computed from its embedding, its link neighbourhood, and its distance from the vault centroid, rank-normalised across the vault. Related notes look related in Obsidian's graph view. |
| Immutability guards | Hooks that block an agent from overwriting the notes you declared yours to write. |
| Twelve skills | Research, source acquisition, video transcription, vault heartbeat, weekly consolidation, plus project-side skills for code, tests, and cleanup. |
Search costs about 64ms end to end and leaves nothing resident. The embedding model runs in-process; lose it and search degrades to BM25 with a warning on stderr rather than breaking.
git clone https://github.com/jacksoswag/ObsidAgent.git && cd ObsidAgent && ./install.sh /path/to/your/vaultThat copies the engine to <vault>/.scripts/, the skills to <vault>/.claude/, and the conventions to <vault>/notes.md. Your notes are never touched.
Then point the tools at it:
export OBSIDAGENT_VAULT=/path/to/your/vault.claude/skills/ and .claude/hooks/ are picked up automatically when the vault is your working directory. To use it from anywhere, symlink the skills into ~/.claude/skills/ and add one line to your CLAUDE.md:
Vault conventions live in `$OBSIDAGENT_VAULT/notes.md`. Read it before reading or writing any note.AGENTS.md at the vault root is the entry point Codex reads on its own. The install script writes it. Skills map to Codex's own skill directory; see AGENTS.md.
python3 .scripts/notes.py -m "what did I conclude about caching" # hybrid search, ranked
python3 .scripts/notes.py -x "CGSSetWindowShape" # lexical only, exact symbols
python3 .scripts/notes.py # index topics and counts
python3 .scripts/reindex.py # rebuild indexes, report problems
python3 .scripts/colorize.py # recompute graph colours
python3 .scripts/health.py # frontmatter and link integritynotes.py -m returns one line per note: score, last-updated, path, description, and the body line that earned the hit. Twenty rows costs roughly 1,400 tokens, which is the point. An agent can afford to search several times before it writes.
Five folders, each answering a different question. vault-template/ is a working starter.
| Folder | Holds | Filename |
|---|---|---|
compass/ |
your standing goals and principles, agent-read, never agent-written | {commitment}.md |
topics/ |
the standing account of a subject, rewritten in place | {topic}.md |
analysis/ |
one operational fact, or one dated pass | {fact}.md / {subject}-YYYY-MM.md |
sources/ |
converted external material, read-only once written | the source's title, kebab-cased |
projects/ |
one document per project | the project name |
The split is the whole design. compass/ holds what you want, everything else holds what is known, and an agent that confuses the two will cheerfully rewrite your goals to match its last finding. The hooks enforce it.
Full conventions, including frontmatter, linking rules, and when to write nothing, are in notes.md.
Python 3.9+. Everything else is standard library. Semantic search wants a local sentence-embedding model; without one you get BM25 and a warning. .scripts/README.md has the two commands that set it up.
No tags. A tag asserts membership and carries no content, so a wrong one is invisible. A broad topic note that names each member and says in a clause what it answers is the replacement, and a wrong one is visible immediately.
Nothing loads on its own. No auto-injected context, no always-on memory. The agent searches when it needs to, which is what keeps the token cost honest.
Every index is generated. Hand-editing one is work the next reindex overwrites.
MIT.