v8.2.0

Writing to the vault worked. Everything around writing to it quietly did not.

The v8 line made this vault reachable from any repo: v8.0.0 shipped the om MCP server and the scoped memory layer, v8.1.0 added reason, v8.1.1 fixed the wiring once a real consumer tried it. v8.2.0 is the first release built from measuring what the memory layer actually did after a day of real cross-repo use. 56 calls, 49 of them from a consuming repo. The capture half was healthy. Three of the four things surrounding it were broken, and every one failed silently.

They share a shape, which is the most useful thing here. Capture fires on an event — you learned something, the tool runs, it happens. Consultation, correct scoping and promotion fire on intention — they happen only if somebody means to. Event-triggered behaviour happens; intention-triggered behaviour decays. Every change below moves a decaying behaviour onto an event.

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

🔌 Enabling the MCP server (one command)

Set up once per machine, not per repo. Nothing here touches the vault itself.

claude mcp add --scope user om node "/absolute/path/to/your-vault/.claude/scripts/om-mcp.mjs"

That covers every directory on the machine, with nothing added to any repository. No environment variable either: the launcher resolves the vault from its own location.

Get the path with cd /path/to/your-vault && pwd.

The per-repo .mcp.json form is still supported, for when you want a specific repo to carry the wiring so a teammate gets it on clone:

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

Warning

Use an absolute path, and don't copy the relative one. This vault's own .mcp.json registers qmd with a relative path, which is correct there because a session in the vault is already in the right directory. Reused for om in another project, the same shape silently resolves against that project instead, and the server never starts.

Step 2 is the one that matters, and it is not optional. The consuming repo needs a short section in its own CLAUDE.md telling it the vault exists and when to reach for it. Written out in full in the README — copy it and fill in the triggers.

Measured, and the reason this step is not paperwork: with the server wired and no repo-side instruction, a session made zero vault calls and implemented a design the vault had recorded as explicitly rejected. With the instruction present, it refused and cited the note. A prohibition in the server's own instructions propagates reliably; a positive "go and look" 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.

v8.2.0 adds one clause to that snippet — see Changed, below.

---

What's new in v8.2.0 — 2026-07-30

Added

• remember warns when a memory claims to reach everywhere without saying why. Of 18 captures written by real sessions, 15 declared scope: "general" — several of them dependency-specific lessons that cannot help anyone on a different stack. A git-library limitation is platform; called general, it becomes noise in every other project's recall. The cause was the schema text: confidence is normative and tells you how to choose, while scope only described what each tier does, never when each is the honest answer. There is now an optional generality field, a warning when general is claimed without one, and its own rendered section so a later reader can judge the reach claim rather than inherit it. It warns rather than rejects: narrowing general by inspecting content was tried once and reverted, and declared reach stays the caller's to declare. Under-reach rejects, because a memory reaching nobody is a correctness bug; over-reach warns. (#173)

Changed

• The repo-side snippet now anchors consultation to an artifact instead of a moment. It said consult the record before changing something — right instruction, wrong point in the task. It fires at the start, which is when a session knows least about what it will need; the moment consultation pays is later, when a decision is about to be committed, and nothing triggered that. Measured: captures ran roughly four times heavier than consultations, so a session could consult once, learn nothing applicable, then make the exact choice a recorded decision had already ruled on. The snippet now asks for the result to appear in whatever you write before implementing: the decisions the work rests on, anything found that argues against the approach, and an explicit "nothing recorded on this" when the record is empty, which is a finding rather than a blank to skip. (#174)

Fixed

• The cross-repo memory inbox was watched by nothing. memories/YYYY/MM/ is where the server writes lessons on behalf of sessions in other repos, and hygiene never reported it once. What made it look covered is that hygiene does have an inbox detector, pointed at a different directory: mcp_inbox is the fallback where a record_work call from an unmatched repo lands, memory_root is where remember writes. In a real vault the watched one held a single README while the unwatched one accumulated 18 captures in a day, with the session report listing ageing captures from everywhere else and never mentioning them. The obvious fix would also have failed silently: the server writes two levels down, under year and month, so a flat listing of the root finds nothing at all and looks exactly like a drained inbox. (#171)
• A capture whose arguments did not serialize was written verbatim, and reported success. A record_work call arrived whose summary ended with its own closing tag and then carried the entire changes array as literal text. The note held raw markup, the changes section never rendered, and nobody noticed until a human saw the tags in Obsidian days later. Every automated signal said success: the call returned, the file was written, each field was a non-empty string — nothing downstream can tell a corrupted capture from a good one, because the corruption is well-formed text in the right field. Both record_work and remember now refuse such a call and name the offending field. It rejects, because a field that has swallowed the following field cannot be repaired by guessing where it ended. Deliberately narrow: a bare </summary> is not matched, since <details><summary> is legitimate prose and matching it would train everyone to work around the guard instead of fixing the call. (#172)

Upgrading

No action required. generality is optional, the serialization guard only refuses calls that were already producing corrupt notes, and the hygiene line is new output rather than changed behaviour.

One habit is worth adopting, and it is the only user-visible contract change:

Important

Promotion into brain/ is additive, and there is now a marker for it.

recall reads only the memory root and never brain/. So promoting a lesson and deleting the capture takes it away from every repo that cannot read brain/ at all — precisely the repos that needed it. Copy it, and leave the entry.

Because the entry stays, add promoted: "<note>" to the capture's frontmatter. That marker is what lets the hygiene count fall: without it, a flag counting every file could only ever grow, and a warning that cannot reach zero by doing the right thing just teaches you to ignore the whole block.

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.1.1