Your AI coding agent forgets everything the moment you close the session. Obsidian Mind fixes that — permanently.
Every AI session starts from zero. No memory of yesterday’s decisions. No recall of that architecture choice from last week. No awareness of your goals, your team, or your patterns.
You re-explain the same context. You lose insights made three conversations ago. The knowledge never compounds.
Obsidian Mind changes this entirely. It turns your Obsidian vault into a persistent external brain for AI coding agents — and every session automatically builds on the last.
Table of Contents
Open Table of Contents
What Is Obsidian Mind?
Obsidian Mind is an Obsidian vault template designed for engineers who use AI coding agents like Claude Code, Codex CLI, or Gemini CLI.
It’s not just a plugin. It’s a complete knowledge architecture that:
- Gives your AI agent memory that persists across sessions
- Automatically routes conversations into structured notes
- Links decisions, people, projects, and wins together
- Tracks your performance for review season — automatically
Think of it as upgrading your AI from a goldfish to an elephant. Same agent, permanent memory.
The Problem It Solves
AI coding agents are powerful but amnesiac. Here’s what happens without persistent memory:
| Session 1 | Session 2 | Session 3 |
|---|---|---|
| ”I’m working on an auth refactor" | "What was I working on again?" | "Remember the auth refactor?” |
| Explain your team structure | Re-explain your team structure | Re-explain again |
| Make a decision about caching | Decision is lost | Make the same decision differently |
| Get praised by your manager | Win is forgotten | No evidence for review |
With Obsidian Mind:
| Session 1 | Session 2 | Session 3 |
|---|---|---|
| ”I’m working on an auth refactor” | Agent already knows — loaded on startup | Continues seamlessly |
| Mention your team once | Agent recalls all people and roles | Suggests relevant context proactively |
| Make a decision about caching | Decision is documented and linked | References it when relevant |
| Get praised by your manager | Auto-added to your Brag Doc | Ready for review season |
How It Works
The Core Architecture
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.
Lifecycle Hooks
Five hooks run automatically to keep everything organized:
| Hook | When | What It Does |
|---|---|---|
| 🚀 SessionStart | On startup | Loads your North Star goals, active projects, recent changes, open tasks |
| 💬 UserPromptSubmit | Every message | Classifies content (decision, incident, win, 1:1) and routes it |
| ✍️ PostToolUse | After writing .md | Validates frontmatter and checks for wikilinks |
| 💾 PreCompact | Before compaction | Backs up session transcript to session logs |
| 🏁 Stop | End of session | Archives completed projects, updates indexes, checks orphans |
You just talk naturally. The hooks handle the routing.
Vault-First Memory
All durable knowledge lives in brain/ topic notes — git-tracked, Obsidian-browsable, and linked. Claude Code’s MEMORY.md acts as an auto-loaded index that points to vault locations, never storing knowledge itself. This means your memories survive machine changes and stay part of the connected graph.
See It in Action
Morning Standup
/om-standup
→ Loads North Star, active projects, open tasks, recent git changes
→ "You have 2 active projects. The auth refactor is blocked on API
contract. Your 1:1 with Sarah is at 2pm — last time she flagged
observability."One command. Full context. Ready to work.
Brain Dump After a Meeting
/om-dump Just had a 1:1 with Sarah. She's happy with the auth work
but wants us to add error monitoring before release. Tom mentioned
the cache migration is deferred to Q2 — we decided to focus on the
API contract first. Win: Sarah praised the auth architecture.What happens automatically:
- ✅ Updated
org/people/Sarah Chen.mdwith meeting context - ✅ Created
work/1-1/Sarah 2026-03-26.mdwith key takeaways - ✅ Created Decision Record: “Defer Redis migration to Q2”
- ✅ Added to
perf/Brag Doc.md: “Auth architecture praised by manager” - ✅ Updated
work/active/Auth Refactor.mdwith error monitoring task
All from a casual paragraph. No manual filing. No templates to fill.
Incident Response
/om-incident-capture https://slack.com/archives/C0INCIDENT/p123456
→ Reads every Slack message, thread, and profile
→ Creates notes for new people involved
→ Generates full timeline, root cause analysis
→ Adds brag doc entry for incident responseEnd of Day
"wrap up"
→ Verifies all notes have proper links
→ Updates indexes
→ Finds uncaptured wins (brag-spotter agent)
→ Suggests improvements for tomorrowKey Commands
Obsidian Mind includes 18 built-in commands that cover the full engineering workflow:
Daily Workflow
| Command | What It Does |
|---|---|
/om-standup | Morning kickoff — loads context, reviews yesterday, suggests priorities |
/om-dump | Freeform capture — routes natural language to the right notes |
/om-wrap-up | End-of-session review — verify notes, indexes, links |
/om-weekly | Weekly synthesis — patterns, North Star alignment, uncaptured wins |
Meetings & People
| Command | What It Does |
|---|---|
/om-capture-1on1 | Capture a 1:1 transcript into structured notes |
/om-prep-1on1 | Prep for an upcoming 1:1 — person context, open items, agenda |
/om-meeting | Prep for any meeting by topic |
/om-intake | Process meeting notes inbox — classify and route |
Incidents & Collaboration
| Command | What It Does |
|---|---|
/om-incident-capture | Capture an incident from Slack into structured notes |
/om-slack-scan | Deep scan Slack channels for evidence |
/om-peer-scan | Scan a peer’s GitHub PRs for review prep |
Performance Reviews
| Command | What It Does |
|---|---|
/om-review-brief | Generate a review brief (manager or peer version) |
/om-self-review | Write your self-assessment with linked evidence |
/om-review-peer | Write a peer review with project and principle data |
Vault Maintenance
| Command | What It Does |
|---|---|
/om-vault-audit | Audit indexes, links, orphans, stale content |
/om-vault-upgrade | Import content from an existing vault |
/om-humanize | Make Claude-drafted text sound like you wrote it |
/om-project-archive | Move completed projects from active to archive |
Subagents: Specialized AI Workers
Obsidian Mind uses subagents — specialized AI workers that run in isolated context windows for heavy operations without polluting your main conversation:
| Subagent | What It Does |
|---|---|
| brag-spotter | Finds uncaptured wins and competency gaps |
| context-loader | Loads all vault context about a person, project, or concept |
| cross-linker | Finds missing wikilinks, orphans, and broken backlinks |
| people-profiler | Bulk creates/updates person notes from Slack profiles |
| review-prep | Aggregates all performance evidence for a review period |
| slack-archaeologist | Full Slack reconstruction — every message, thread, profile |
| vault-librarian | Deep vault maintenance — orphans, broken links, stale notes |
| review-fact-checker | Verifies every claim in a review draft against vault sources |
The brag-spotter is particularly valuable — it scans your conversations for achievements you didn’t think to document and adds them to your Brag Doc automatically.
Agent Compatibility
Obsidian Mind works with multiple AI coding agents:
| Agent | Support Level | Details |
|---|---|---|
| Claude Code | ✅ Full support | Hooks, commands, subagents, memory system |
| Codex CLI | ✅ Hooks + commands | Reads AGENTS.md, hook config at .codex/hooks.json |
| Gemini CLI | ✅ Hooks + commands | Reads GEMINI.md, hook config at .gemini/settings.json |
| Cursor, Windsurf, Copilot | 🟡 Partial | Reads AGENTS.md for vault conventions, hook support varies |
All hooks, commands, and subagent prompts are agent-agnostic — pure Markdown, Python, and shell with zero SDK dependencies.
Smart Token Management
A common concern: “Won’t loading my entire vault burn through tokens?”
Obsidian Mind uses tiered loading to keep costs minimal:
| Tier | What Loads | When | Token Cost |
|---|---|---|---|
| Always | North Star excerpt, git summary, tasks, file listing | Session start | ~2K tokens |
| On-demand | Semantic search results (via QMD) | When agent needs context | Targeted |
| Triggered | Classification routing hints | Every message | ~100 tokens |
| Triggered | Write validation | After .md writes | ~200 tokens |
| Rare | Full file reads | Only when explicitly needed | Variable |
The agent queries by meaning first (via semantic search), then reads only what’s relevant. Your vault can contain thousands of notes — the agent only loads what it needs.
Getting Started
Prerequisites
- Obsidian 1.12+ (for CLI support)
- An AI coding agent: Claude Code, Codex CLI, or Gemini CLI
- Python 3.8+
- Git
Setup (5 Minutes)
# Clone the vault
git clone https://github.com/breferrari/obsidian-mind.git
cd obsidian-mind
# Open as an Obsidian vault
# Enable Obsidian CLI in Settings → General
# Optional: Enable semantic search
npm install -g @tobilu/qmd
qmd collection add . --name vault --mask "**/*.md"
qmd update && qmd embedFirst Steps
- Open the vault in Obsidian
- Fill in
brain/North Star.mdwith your goals — this grounds every session - Run your agent in the vault directory (
claude,codex, orgemini) - Start talking about work
That’s it. The hooks handle everything from there.
Recommended Daily Workflow
| Time | Action |
|---|---|
| Morning | Run /om-standup — get full context and priorities |
| During the day | Talk naturally — hooks route everything automatically |
| After meetings | Use /om-dump to narrate what happened |
| End of day | Say “wrap up” — agent verifies and closes out |
| Weekly | Run /om-weekly for cross-session synthesis |
Frequently Asked Questions (FAQ)
Does it only work with Claude Code?
No. Obsidian Mind has full support for Claude Code and working hooks for Codex CLI and Gemini CLI. The vault conventions work with any agent that can read Markdown.
Will it make my AI sessions expensive?
No. The tiered loading system keeps token usage minimal (~2K tokens at session start). The agent only reads full files when explicitly needed.
Can I use my existing Obsidian vault?
Yes. Use the /om-vault-upgrade command to import and classify content from your existing vault into the Obsidian Mind structure.
What if I don’t use Slack?
The Slack-related commands (/om-incident-capture, /om-slack-scan) are optional. The core workflow — standup, dump, wrap-up, weekly — works without Slack.
Is my data private?
Yes. Everything stays in your local Obsidian vault and Git repository. No cloud service required. Your AI agent processes data locally through its normal API — Obsidian Mind doesn’t add any external data transmission.
How is this different from just using MEMORY.md?
MEMORY.md is a flat file with session notes. Obsidian Mind is a connected knowledge graph — notes link to each other, subagents process and categorize information, and the lifecycle hooks ensure nothing falls through the cracks.
Obsidian Mind is open source (MIT license) and available at github.com/breferrari/obsidian-mind. Give your AI agent the one thing it’s always been missing — memory that lasts.