Your AI Coding Agent Forgets Everything. This Obsidian Vault Fixes That.

By Prahlad Menon Published 2026-04-14 8 min read

Every AI coding agent has the same problem: it forgets.

You spend twenty minutes explaining your project structure, your team’s conventions, a decision you made last week about the auth flow. The session ends. You come back tomorrow and it’s all gone. You explain it again. The knowledge never compounds.

obsidian-mind is a GitHub template that fixes this — not with a vector database, not with a custom memory API, but with an Obsidian vault wired directly into your agent’s session lifecycle.

It works with Claude Code (full support), Codex CLI, and Gemini CLI. Same hooks, same commands, same vault.

The Core Idea

The insight is simple: Obsidian is already a knowledge graph. It has wikilinks, backlinks, database-style bases, templates with frontmatter, and a CLI. If you structure your vault correctly and hook it into your agent’s startup/shutdown lifecycle, your agent can maintain its own memory — reading context when it starts, filing information as you talk, and updating indexes when it wraps up.

You stop re-explaining things. Every session builds on the last.

You: "start session"
Agent: reads North Star, checks active projects, scans recent memories
Agent: "You're working on Project Alpha, blocked on the BE contract.
        Last session you decided to split the coordinator. Your 1:1
        with your manager is tomorrow — review brief is ready."

That’s not magic. That’s a well-structured vault and five lifecycle hooks.

The Hook-Based Session Lifecycle

This is the most technically interesting part of obsidian-mind. Rather than relying on you to manually load context, it uses agent hooks — event-driven scripts that fire automatically at the right moment.

Hook	When	What it does
`SessionStart`	Startup / resume	Re-indexes with QMD, injects North Star goals, active projects, recent git changes, open tasks, vault file listing
`UserPromptSubmit`	Every message	Classifies content (decision, incident, win, 1:1, architecture, person, project update) and injects routing hints
`PostToolUse`	After writing `.md`	Validates frontmatter, checks for wikilinks
`PreCompact`	Before context compaction	Backs up session transcript to `thinking/session-logs/`
`Stop`	End of session	Archive completed projects, update indexes, check orphans

The UserPromptSubmit hook is particularly clever. Every message you send gets classified — the hook is a lightweight Python call that nudges the agent toward filing things correctly without you having to think about it. Mention a decision you made in passing, and it gets routed to a Decision Record. Mention a win, and it lands in the Brag Doc.

You just talk. The hooks handle the routing.

Token-Efficient by Design

The naive approach to agent memory is to dump everything into context on every session. obsidian-mind explicitly rejects this with a tiered loading strategy:

Tier	What	Cost
Always	`CLAUDE.md` + lightweight SessionStart context (North Star excerpt, git summary, tasks, vault file listing)	~2K tokens
On-demand	QMD semantic search results	Targeted
Triggered	Classification routing hints	~100 tokens/message
Triggered	PostToolUse validation	~200 tokens on `.md` writes
Rare	Full file reads	Only when explicitly needed

SessionStart loads excerpts and filenames, not full note contents. When the agent needs specific context — “what did we decide about caching?” — it queries the vault semantically via QMD before reading files. It pulls only what’s relevant.

This keeps your token costs manageable even as the vault grows to hundreds of notes.

The Vault Structure

The folder layout is intentional. Notes live in one folder (their home) but link to many notes (their context). The agent maintains this graph automatically — linking work notes to people, decisions, and competencies as conversations happen.

brain/          North Star, Memories, Key Decisions, Patterns, Gotchas
work/           active/, archive/, incidents/, 1-1/
org/            people/, teams/
perf/           Brag Doc, competencies/, evidence/, review briefs
reference/      Codebase knowledge, architecture maps
thinking/       Scratchpad — promote findings, then delete

A note without links is a bug. That’s a design principle, not a suggestion. The cross-linker subagent enforces it during vault audits.

The Performance Tracking Angle

This is the part that surprised me most. obsidian-mind doubles as a performance tracking system, and it’s genuinely useful.

Here’s how it works: perf/competencies/ contains one note per competency in your org’s framework. As you do work, notes link back to relevant competencies in their ## Related section. Backlinks accumulate automatically. When review season arrives, the backlinks panel on each competency note is already the evidence trail — you don’t reconstruct it from memory, it’s been building all year.

The /om-review-brief command aggregates everything — brag entries, decisions, incidents, competency evidence, 1:1 feedback — into a structured review brief. The review-fact-checker subagent then verifies every claim against vault sources before you submit.

/om-peer-scan @colleague
# → deep-scans their GitHub PRs
# → writes structured evidence to perf/evidence/
# → links to relevant competency notes

If you’ve ever scrambled to remember what you shipped six months ago during review season, this is the answer.

18 Commands, 9 Subagents

The command set covers the full work lifecycle:

/om-standup — morning kickoff with context, tasks, suggested priorities
/om-dump — freeform brain dump, routes everything to the right notes
/om-incident-capture — capture an incident from a Slack link into structured notes (with slack-archaeologist doing the heavy lifting)
/om-weekly — cross-session synthesis, North Star alignment, uncaptured wins
/om-wrap-up — end-of-day: verify notes, update indexes, spot wins

Subagents run in isolated context windows for heavy operations — brag-spotter, context-loader, cross-linker, people-profiler, review-prep, slack-archaeologist, vault-librarian, review-fact-checker, vault-migrator. They handle the expensive work without polluting your main conversation.

Multi-Agent: Not Just Claude Code

Most memory systems for AI agents are Claude Code-specific. obsidian-mind took the time to make it genuinely portable:

Claude Code — full support, hooks wire in natively via settings.json
Codex CLI — reads AGENTS.md natively, hooks configured at .codex/hooks.json
Gemini CLI — reads GEMINI.md natively, hooks mapped at .gemini/settings.json
Cursor, Windsurf, GitHub Copilot — read AGENTS.md for vault conventions (hook support varies)

The vault itself — the folder structure, templates, commands, and brain/ notes — works the same regardless of which agent you’re running. Only the auto-memory loader (~/.claude/MEMORY.md) is Claude Code-specific.

Getting Started

# Clone or use as GitHub template
git clone https://github.com/breferrari/obsidian-mind your-vault

# Open as Obsidian vault
# Enable Obsidian CLI in Settings → General (requires 1.12+)

# Run your agent in the vault directory
cd your-vault && claude   # or: codex, gemini

# Fill in your goals
# brain/North Star.md — this grounds every session

# Optional: add semantic search
npm install -g @tobilu/qmd
qmd collection add . --name vault --mask "**/*.md"
qmd update && qmd embed

QMD is optional but recommended for larger vaults — it’s what enables “find what we decided about caching” even when the note is titled “Redis Migration ADR.”

How It Compares to Other Agent Memory Approaches

obsidian-mind isn’t the only solution to the agent amnesia problem. We’ve covered the landscape extensively — here’s where it sits:

soul.py is a Python library that gives any LLM agent persistent memory with zero dependencies. Where soul.py is a primitive — a building block you embed into your own agent stack — obsidian-mind is an opinionated system built specifically for coding agents running in a vault. soul.py is more portable; obsidian-mind is more complete out of the box. We’ve also compared the RAG+RLM hybrid approach in soul.py v2 which tackles the same retrieval problem QMD solves here.

Lore takes the fully local, fully private angle — a system tray app with a hotkey for capturing thoughts, running entirely via Ollama and LanceDB. No cloud, no API keys. Where Lore is personal knowledge capture, obsidian-mind is workflow memory for a coding agent. Different use cases, but both built on the “files are enough” philosophy.

Memvid packages embeddings and search into a single portable .mv2 file — no vector database required. obsidian-mind uses QMD for semantic search, which requires a running index. Memvid wins on portability; obsidian-mind wins on human readability and the Obsidian graph.

Memory as a System vs Memory as a File — we covered this debate directly when comparing Google ADK’s always-on consolidation daemon vs soul.py’s file-based retrieval. obsidian-mind comes down firmly on the “files” side: your memory is Markdown, it’s git-tracked, it’s human-readable, and it lives in Obsidian’s graph. No server, no daemon.

Markdown vs. Graph Database memory — OpenLobster replaced MEMORY.md with Neo4j and called flat markdown “a wiki, not a memory system.” obsidian-mind’s answer is essentially: Obsidian is a graph, not flat markdown. Wikilinks, backlinks, and bases give you graph-like navigation without running a database. A middle path worth considering.

The pattern across all these tools is the same: the “memory problem” in AI agents is fundamentally a retrieval problem. obsidian-mind’s bet is that Obsidian’s graph + QMD semantic search is sufficient for a coding agent’s needs — and that the human-readable, git-tracked, always-inspectable format is a feature, not a compromise.

Why This Matters

The problem obsidian-mind solves is real and underappreciated. AI coding agents are getting dramatically more capable, but their amnesiac nature means the knowledge you build with them evaporates between sessions. You end up doing the same onboarding work over and over. The agent never learns your patterns, your team, your codebase’s quirks.

Giving the agent a well-structured, link-rich, semantically-searchable knowledge graph — and hooking it into the session lifecycle so it reads and writes that graph automatically — is a genuinely good solution. It doesn’t require a server, it doesn’t require an API key, and it lives in a format (Markdown + Obsidian) that you can read, edit, and version-control yourself.

The knowledge compounds. That’s the point.

obsidian-mind → github.com/breferrari/obsidian-mind
Created by Brenno Ferrari · MIT License