
Three weeks ago Claude Code told me we hadn't decided on a database. That decision had been logged two days earlier, in the same CLAUDE.md file it was reading. The information wasn't missing. Nothing in the system knew which paragraph still mattered. Obsidian Second Brain pitches 45 slash commands as the fix, persistent memory for Claude Code stored in markdown, but they all serve four core jobs. The real question is which of those jobs are real and which are decoration, especially after one scheduled agent reinstalled a different virtualenv's requirements into my active shell overnight and cost me a chunk of a morning tracing it. The rest of this post sorts out which of the 45 commands earn a place in a real project and which ones you should turn off before they touch your environment.
The pitch is persistent memory for Claude Code and six other CLI agents, stored as plain markdown in an Obsidian vault, with 45 slash commands covering semantic search, self rewriting notes, web research without an API key, and scheduled agents that groom the vault overnight. My stance after running it on a real client project: the memory layer earns its place. The scheduled agent piece is what most people will turn off within a week, and the next few sections explain why in order.
Does Markdown Memory Actually Beat A Long CLAUDE.md File?
45 Commands Shipped, Only 8 Do Real Work
Source: Based on author's hands on testing of Obsidian Second Brain, as described in the article
The common assumption is that a single well organized CLAUDE.md is enough. Keep it tight, update it by hand, treat it like a README for the AI. That works for small projects. It stops working once you have more than one active workstream, because the file becomes a flat list competing for the same context window as your actual task, and Claude Code has no way to know which paragraph from four months ago still matters. That's the exact failure from the opening: a decision was in the file, but nothing marked it as current.
Obsidian Second Brain splits memory into project notes, decision logs, and a people and entities layer, all living as separate markdown files in a real Obsidian vault, then uses hybrid semantic search to pull only the relevant notes into context instead of dumping the whole history. Hybrid here means it's not pure embedding similarity. It blends keyword matching with vector search, which matters in practice because pure semantic search tends to miss exact terms like a specific library version or an internal codename that embeddings treat as noise.
The command that sold me was /obsidian-decide. Instead of me manually writing a decision log entry and hoping I remember to update it next session, it writes directly to the relevant project note, and the --formal flag produces a full ADR style record with the reasoning intact.
/obsidian-decide --formal "Switched from REST polling to websocket push for the dashboard, polling was eating into our API quota"
That one command replaced a habit I never actually kept up with on my own: writing architecture decision records in real time. The honest tradeoff is that your vault now has an opinion about your project that your git history doesn't, and if the two drift apart you have to decide which one is telling the truth. 45 is the number of commands shipped. Eight of them are doing the real work, and /obsidian-decide is one of the eight.
What Happens When The Vault And The Codebase Disagree?
How Obsidian Second Brain Structures Memory
All notes flat, competing for the same context window
Project notes, decision logs, people and entities, as separate markdown files
Blends keyword matching with vector search, pulls only relevant notes
Decision logged directly to the project note, with reasoning intact
Stale notes still get surfaced unless /obsidian-learn prunes them
Source: Derived from the article's description of the memory layer and the /obsidian-decide workflow
The decision log solves one problem and opens another: once the vault starts recording state, that state can go stale. People assume a persistent memory layer is additive, strictly more context, strictly a win. Nobody warns you about staleness upfront. A note written three sprints ago that says you're using Postgres for session storage is still technically true to the system and still gets surfaced by semantic search, even after you migrated to Redis last Tuesday and never told the vault.
/obsidian-learn is supposed to help here. It reviews vault learnings, prunes the stale ones, and surfaces repeated patterns worth promoting into standing rules. In practice it caught less than I expected. It flagged a note about an API rate limit we'd since raised, but missed a note describing a now deleted microservice, probably because nothing in my recent commands directly contradicted it. There was just no new information to trigger a review. That's a reasonable design choice, actually. Pruning by contradiction rather than by staleness heuristics is safer, but it means the vault accumulates dead weight quietly if your prompts never happen to touch the stale area again.
I ran into a sharper version of this during a Python debugging session that had nothing to do with vault content directly, but everything to do with the same scheduled process that's supposed to keep the vault current. I was chasing a ModuleNotFoundError: No module named 'yaml' inside a venv where I was certain PyYAML was installed. Three fixes in, the one that actually worked was realizing the vault's scheduled agent had quietly reinstalled a different virtualenv's requirements file into the active shell during an overnight run, because the cron style job inherited a stale PATH.
# what fixed it, after pip install pyyaml and reactivating the venv both failed
echo $VIRTUAL_ENV
which python
python -m pip install --force-reinstall -r requirements.txt
None of that is really the tool's fault. It's a reminder that anything running on a schedule in the background shares your environment whether you remember granting it that access or not. That misfired cron window is the same one that cost me a chunk of my morning, and it's the first sign that the scheduled agents deserve closer scrutiny than the rest of the toolkit, which the next two sections take up directly.
Is Key Less Web Research Actually Key Less?
Command Categories: What To Keep, What To Cut
| Core Job | Example Command | Verdict |
|---|---|---|
| Decision logging | /obsidian-decide | Keep, core value |
| Memory pruning | /obsidian-learn | Keep, catches staleness |
| Semantic search | Hybrid vault search | Keep, beats flat file |
| Scheduled overnight agents | Vault grooming agent | Turn off, caused env damage |
Source: Author's assessment of Obsidian Second Brain's command set, as described in the article
Before getting to the scheduled agents themselves, it's worth covering the other feature that sounds safer than it is: web research with no API key. The README leans on the phrase key less web research like it's a settled feature rather than a design decision with consequences. The common assumption, especially for anyone who has set up a dozen MCP servers already, is that key less means no setup cost. The reality is closer to this: no API key to manage, but a different, less visible cost in reliability.
What it actually does is scrape and parse public web results directly rather than routing through a paid search API like Brave Search or Tavily. That avoids the monthly key rotation headache and the moment where you discover your free tier research API quota reset at midnight UTC and you're three requests over. But it also means your research quality is tied to whatever scraping approach survives the target site's current HTML structure, and that's the kind of thing that breaks without a changelog entry when a site redesigns its search results page.
I tested this against a question about a recent library's breaking changes between two minor versions. It got the broad strokes right, but missed a changelog detail that a paid search API with structured results had caught the week before in a separate test. Key less is a real advantage for casual use and for people who don't want another credential in their password manager. It's not yet a replacement for a paid research API when the answer needs to be precise down to a version number.
- No API key required for setup
- No monthly quota to track
- No credential rotation
- Lower precision on structured or recent data
- And a dependency on scraping resilience that you're trusting the maintainers to keep up with as sites change.
Each of these points at the same tradeoff: setup friction goes down while answer precision becomes harder to guarantee. That's fine for exploratory research, the kind where you want three plausible angles on a problem, and it's a weaker fit for anything where being slightly wrong is worse than returning nothing. The project is honest about this being a design choice rather than a strictly superior approach, which is more than most tool READMEs manage.
Do The Scheduled Agents Maintain The Vault Or Just Add Noise?
The research tradeoff above is a visible one: you can see when an answer is thin. The scheduled agents are different, because their mistakes don't announce themselves. They're also the feature that sounds the most impressive in the pitch, and the one I ended up disabling first. The marketing assumes a vault maintaining itself while you sleep is strictly a convenience, more automation, less manual upkeep, nothing to lose. The actual experience is closer to running a second, less supervised version of Claude Code against your own notes, and supervision is exactly what you lose, which lines up with the stale-PATH incident from two sections back: the same overnight process that's supposed to groom the vault is the one that reached outside it.
On the first overnight run, the agent pruned a note I'd tagged for manual review, treating my tag as stale metadata rather than an explicit hold. Nothing catastrophic happened. Obsidian's version history meant I could restore it fairly quickly, but it was a reminder that scheduled autonomous edits to your own knowledge base need the same caution you'd give a cron job that touches production data.
Here is roughly what the scheduling configuration looks like once you commit to it:
schedule:
obsidian_maintain:
cron: "0 3 *"
commands:
, /obsidian-learn
, /obsidian-visualize
guardrails:
dry_run_first: true
max_notes_modified: 10
require_tag_exclude: "pinned"
The guardrails exist, which tells you the maintainers already anticipated this exact failure, but dry_run_first isn't the default. You have to know to add it. Set max_notes_modified too high and a single bad run can touch more of your vault than you'd ever approve by hand in one sitting. I now run the scheduled job with dry_run_first on permanently and review the diff each morning, which costs some of the sleep while it works pitch but keeps me from losing notes I actually need.
The visualize command, by contrast, has been reliably useful and low risk, because a canvas map of your second brain is read only by nature. There's nothing to prune or rewrite, just a graph. If the project split scheduled agents into read only maintenance and write capable maintenance as separate opt ins, adoption of the write side would likely go up, because right now the two are bundled under one trust decision.
Does This Replace An MCP Server Or Compete With One?
The scheduled agent failures above were quiet by nature: a wrong prune, a stray requirements install, nothing that threw an error. That quietness turns out to be a structural property of the whole project, not just the scheduler, and it shows up again when you compare it to an actual MCP server for Obsidian, since there are a few floating around that expose vault read and write operations over the Model Context Protocol directly. You'd assume Obsidian Second Brain is just another MCP server with better branding. It isn't, and that distinction changes how you should think about failure cases.
This project operates through Claude Code's command and skill system, slash commands and markdown conventions, rather than running as a standalone MCP server process that Claude Code talks to over a protocol boundary. The practical difference shows up when something breaks. An MCP server failure usually surfaces as a connection error, something explicit in the Claude Code session log, a clear point of failure you can restart. A convention based system fails more quietly: the note didn't get updated the way you expected, but nothing threw an error, because nothing was technically wrong. The agent just made a different judgment call than you wanted.
I hit this during a session where /obsidian-init generated the initial _CLAUDE.md, index.md, and log.md files, but the index didn't pick up a nested project folder three levels deep. No error, no warning, just an index that was quietly incomplete until I noticed a project missing from a later search.
obsidian-second-brain/
_CLAUDE.md
index.md # missed /clients/acme/internal/billing-v2
log.md
projects/
acme/
personal-site/
That's a one time fix once you know to check for it, but it shows the broader shape of the risk: convention based systems degrade gracefully and silently, protocol based systems fail loudly and immediately. Neither is strictly better. Loud failures are easier to debug. Silent degradation is easier to live with day to day until it compounds. For a solo developer managing one evolving vault, I'd rather have the quiet version. For a team sharing one vault across multiple people's Claude Code sessions, I'd want the loud one, because silent drift in a shared knowledge base is much harder to trace back to its source.
The AI-FIRST.md file the project ships as a standalone artifact is worth separating out from the rest of the tool entirely. It's a fifty line note specification you can paste into any CLAUDE.md or AGENTS.md file. It installs nothing, works with no dependency on the rest of the project, and the only ask is that you keep the attribution line. That's the most portable part of the whole repository, and it's the piece I'd recommend to someone who wants the memory discipline without taking on the vault, the scheduled jobs, or the forty five commands.
The database decision that opened this post is exactly the kind of thing a tool like this is supposed to prevent from getting lost. It would have, if the vault and the project state had stayed in sync, which is the whole tension this post has been working through. Two weeks in, my actual workflow uses six of the forty five commands daily, treats the scheduled agents as a manual Sunday chore rather than an overnight one, and keeps the AI-FIRST.md convention in every new CLAUDE.md regardless of whether the full tool is installed. Six out of forty five commands, running on my schedule instead of a cron job's, is what finally made the memory layer trustworthy enough to replace the habit it was supposed to replace in the first place.