Skip to content

v8.1.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 27 Jul 10:48
v8.1.0
aa16349

Your vault stops being a place you have to be sitting in.

The v8 line made this vault reachable from a coding session in any other repository — search your notes, follow the graph, ask it a judgement question, and record what was learned back into it, without leaving the repo you're working in. v8.0.0 shipped the om MCP server and the scoped memory layer; v8.1.0 adds reason, makes recall faster, and fixes two flags that were quietly wrong.

If you skimmed the v8.0.0 notes, this is the part that was compressed into a single line. It's the reason the major version moved.

Quick Start

Requirements: Obsidian, Node 22+ LTS, and one of: Claude Code · Codex CLI · Gemini CLI

Install via ShardMind (recommended — wizard, optional modules, managed upgrades):

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

Or clone directly:

git clone https://github.com/breferrari/obsidian-mind.git
cd obsidian-mind
npm install -g @tobilu/qmd && qmd index && qmd embed   # optional: semantic search

Open the folder as an Obsidian vault, then run claude, codex, or gemini in the directory and type /om-standup (or om-standup in Codex).

Or download the vault zip below and extract it into your Obsidian vaults folder.

Already using obsidian-mind? Just tell your agent: Update this vault to the latest obsidian-mind from https://github.com/breferrari/obsidian-mind

🔌 Enable the MCP server (~3 minutes)

This is set up once per repo that should be able to reach your vault. Nothing here touches the vault itself.

1. Get your vault's absolute path

cd /path/to/your-vault && pwd

2. Register the server in the other project

In the repo you want to give vault access — not the vault — create or edit .mcp.json at its root:

{
  "mcpServers": {
    "om": {
      "command": "node",
      "args": ["/absolute/path/to/your-vault/.claude/scripts/om-mcp.mjs"]
    }
  }
}

3. Tell that project the vault exists

Add this to the same repo's own CLAUDE.md (create it if there isn't one):

## Project memory — the obsidian-mind vault

An `om` MCP server exposes my Obsidian vault to this repo.

Before designing anything non-trivial, or whenever you need prior context:

- `recall` — durable lessons scoped to this repo
- `search` — semantic + keyword search across my notes
- `reason` — judgement across several notes ("is this consistent with what we already decided?")

**Do not implement a design without first checking whether the vault already
records a decision about it.**

When this session produces a lesson that will still be true in a different
repo, record it with `remember`. Use `record_work` for what happened here.

Important

Step 3 is not paperwork, and skipping it is the one way to make this look broken.

Measured: with the server wired and no repo-side instruction, a session made zero vault calls and went on to implement a design the vault had recorded as explicitly rejected. With the instruction present, it refused and cited the note.

The asymmetry is in how MCP instructions propagate. A prohibition holds 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. That's why the snippet above is written as a law, not a suggestion.

4. Verify

Restart the session in that repo and ask it to run health. It reports whether the wiring is intact, which repo it thinks is calling, and where that name came from.

Tip

Repos are identified by folder name — 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.

Warning

Don't register the raw qmd server in a consuming repo as a shortcut. It searches every note directly with no notion of which memories were written for which project, so the repo matches against lessons meant for unrelated ones. Applying each memory's declared scope is exactly what om adds — going around it returns the wrong things, not merely more of them.

🧠 What you actually get

Seven tools, in the session's menu alongside Read and Edit:

tool what it does
search semantic + keyword search over your notes
expand a note's graph neighbourhood — links out and backlinks
recall durable lessons scoped to the calling repo, most specific first
remember record a lesson that will still be true in a different repo
record_work record what happened in this repo, filed where it belongs
reason judgement across several notes — spawns a second session
health is the wiring intact?

reason is the one that thinks. The others retrieve. This one reads the vault with a second Claude session and answers the questions that need judgement across notes — is what I'm 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're already working at: it's Claude, on your machine, under your auth. Every call is logged with its cost, turns, model and wall time. Answers are marked confidence: inferred and are never recorded as memories on their own — your session decides whether any of it is worth keeping. If a run ends early you get no answer rather than a truncated one, because a partial synthesis presented as complete is the only outcome worse than none.

Memory that knows where it belongs. Every memory declares its reach when written:

  • scope: project → reaches only the repos you name
  • scope: platform → any repo on that platform
  • scope: general → everywhere

A reader never widens what the writer declared, so a sibling app on the same platform doesn't inherit another app's constraints. Reach is declared at write time, never guessed at read time. Everything carries confidence: verified | inferred | unverified, dated volatile facts, and provenance derived server-side — a session can't claim to be a project it isn't. Corrections supersede rather than overwrite, so the store gets more trustworthy as it grows instead of accumulating contradictions. recall with explain: true tells you why each memory was shown and how many were withheld.

Your vault, your notes, your session. The default exposure 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 only if this vault holds material that isn't yours to share. A note tagged private is never served, and memories are never served as ordinary notes since they carry their own scope. Every read is logged with the calling repo, so "what did that session actually see" is answerable afterwards.

Want the mechanics? ARCHITECTURE.md → Reaching the Vault From Another Repo walks the whole layer with diagrams: the four MCP surfaces, the identity handshake, a search call traced end to end, how each memory's reach is evaluated, and every failure mode against the signal that reveals it.

What's new in v8.1.0 — 2026-07-27

Added

  • reason — ask the vault a judgement question. Answers questions that need inference across several notes, by reading the vault in a second session on your own default model. Reach for it when search or recall returned the notes but not the judgement.

Changed

  • Recall got faster. Memory parsing is cached, and the memory index no longer reads whole files just to see their head — noticeable on a vault with a lot of recorded memories.

Fixed

  • Sessions were being fed the engine's own files as if they were your notes. The startup file listing walked .shardmind/ — the cached copy of the template used as the three-way-merge base, plus every pre-update backup snapshot. On one real install, 75% of the listing was engine artifacts against 37 actual notes, and it got worse with each shardmind update rather than with vault growth. If you installed or upgraded via ShardMind, this one is for you. (#156)
  • A hygiene flag that could never be cleared. The meetings-inbox pressure warning counted the folder's own README.md — scaffold that /om-intake never drains — so a vault with a genuinely empty inbox was told to drain it on every single session, with the age climbing forever. On a tidy vault it was the only flag you'd ever see. (#155)

Both fixes were reported by @simefirmi from a real v7.0.1 install, with diagnoses accurate enough to land nearly as written. The listing bug in particular is invisible from inside this repo — .shardmind/ holds no notes here — so it could only ever have surfaced from someone running an installed vault. Thank you.

Upgrading

No action required, no config changes, no migration. Both fixes take effect at your next session start.

shardmind update          # if you installed via ShardMind

Or tell your agent: Update this vault to the latest obsidian-mind from https://github.com/breferrari/obsidian-mind

Full history: CHANGELOG.md · Previous release: v8.0.0

Assets 3
Loading