Self-sustained Vault: Graph, Vector, and the ER Bridge

[rosettaguo]

Disclaimer

Is this project open source? It is source-available under the PolyForm Perimeter License.
Is this project completely free? Optional. It is local and free by default. Cloud-based vector and reasoning model APIs may incur third-party costs.
Is this project vibe-coded beyond the author’s ability to comprehend how it works? No. Understory’s architecture is explained in its website.
Community Directory: Understory

Understory: Graph, Vector, and the ER Bridge

Hi everyone. I’m Rosetta, and I’d like to introduce Understory, an Obsidian Community plugin for turning a growing vault into a continuously analyzed memory layer.

The goal is not only to find related notes.

As a vault grows, I want Obsidian to help maintain a living memory of the work inside it: relationships between notes, stale assumptions, possible conflicts, project/entity connections, and changes that should be carried forward over time.

Understory approaches this with three signals:

Graph

A vault has structure: links, backlinks, clusters, central notes, orphan pages, and broken paths.

Understory uses graph analysis to help reveal how the vault is organized, where knowledge paths are missing, and which areas may need maintenance.

Vector

Some notes are related even when they do not share exact words or explicit links.

Understory can run in local-only mode, but it can also use user-configured cloud vector models for stronger semantic recall. With a good vector provider, it becomes much better at finding conceptual relationships across a large vault.

ER Bridge

Some relationships are not just semantic similarity. They are explicit facts: a person owns a project, a concept depends on another concept, a team belongs to an organization, or a decision affects a roadmap.

Understory keeps a local entity-relationship bridge so these harder relationships can participate in vault maintenance. Two notes may not sound alike, but if they refer to the same project, person, organization, or decision chain, Understory can still connect them.

Conflict and update memory

The part I care about most is continuous maintenance.

Understory is meant to help discover relationships, but also to surface possible conflicts, stale notes, orphan pages, broken knowledge paths, and update needs over time. With optional reasoning models configured by the user, this analysis can become much more useful for detecting contradictions and explaining why something may need attention.

That is why I think of it as an agent memory engine for Obsidian: not a separate cloud database, but a local-first memory layer under the vault that both humans and optional local agents can query.

Privacy modes

Understory starts in Local only mode.

Optional cloud model use is explicit and user-configured. You can choose local-only, vector-only, or full AI analysis with your own provider settings.

Understory team does not receive your vault content, prompts, embeddings, model responses, logs, or API keys.

What it does today

• Shows relationship and maintenance suggestions in the right sidebar.
• Uses graph, vector, and ER signals to analyze a vault.
• Flags possible conflicts, stale notes, orphan pages, and broken knowledge paths.
• Maintains local reports and caches in .understory.
• Provides an optional local MCP/CLI interface so agents can query scoped vault context.

I’d especially like feedback from people with large or long-running vaults:

• Does Graph + Vector + ER Bridge match how you think about vault memory?
• What kinds of conflicts or stale assumptions would you want Obsidian to notice?
• How active should a plugin be when helping maintain a vault over time?

[rosettaguo]

What was fixed recently​

Hi everyone & Happy Independent Day for the US users​. Here is a small maintenance note.

I recently fixed two first-run issues that affected some new installs:

1. Local engine shown as missing / not ready

   Understory now recovers better when the bundled local engine exists but the saved engine path or Python path is stale or invalid.

   On macOS, for example, some systems do not have a python command, but do have python3 at paths such as:

   /opt/homebrew/bin/python3
   

   Newer releases try to detect and repair this automatically.

2. api.py exited with code 1 after first run

   This could happen when a new install had not built its Embedding index yet.

   Understory now treats a missing Embedding cache as a recoverable setup state. Instead of only surfacing a raw Python exit code.

The little latency

The Obsidian Community Plugins directory can sometimes take a little while to show the newest release after it is published on GitHub. If the Community Plugins UI has not shown the newest Understory version yet, you can install the latest GitHub release directly here:

Latest GitHub release

Current latest release: 1.8.10

[rosettaguo]

Understory’s MCP + Skill setup

A few users have asked what the MCP and the matching Skill in Understory are for, and why both are included.

The short version:

• MCP gives an AI agent Understory-scoped access to one Obsidian vault.
• The Understory Skill tells the agent when and how to use that access.

One without the other is incomplete: MCP provides tools, while the Skill provides the workflow and safety rules.

What the MCP does

In Settings → Understory → AI agents, Understory can generate a vault-specific local MCP server and a ready-to-paste configuration for Codex, Claude Desktop, Cursor, OpenClaw, or another stdio-compatible client.

It is local-only:

• It is bound to the currently open vault, not every vault on your computer.
• It uses stdio and does not open an HTTP port.
• It returns scoped snippets and relation metadata by default, rather than full note bodies.
• It does not automatically modify your external AI-client configuration.

The available read tools let an agent:

• search the vault using local keyword and known relation-graph signals;
• retrieve a focused context package for a query or a known note;
• inspect a note brief, its relations, or vault-level graph/risk counts;
• check capabilities and local-engine status.

There are also explicit write tools for refreshing, accepting, rejecting, or inserting relations. Those change local vault metadata or note content, so they are intentionally separated from ordinary retrieval.

What the Skill does

The generated Understory Skill is the instruction layer that travels with that MCP configuration.

It tells the agent to:

• use Understory retrieval before broad filesystem reading when vault context is relevant;
• turn search results into a useful answer, reading path, or knowledge map—not a dump of matching notes;
• avoid scanning the whole vault or returning full note bodies by default;
• explain and obtain confirmation before any write action.

How to use them together

1. Open Settings → Understory → AI agents.
2. Choose your agent profile and either Query-only or Agent memory model.
3. Create the local MCP server file and paste the generated MCP JSON into your AI client.
4. Copy or export the matching Understory Skill and add it to that agent’s instructions/skills.

Then a practical workflow can look like this:

“Help me prepare a project brief using my vault.”

---

I’d especially welcome feedback from people using multiple vaults, or from anyone who has tried this with Codex, Claude Desktop, Cursor, or OpenClaw: which setup step or workflow still feels unclear?

[rosettaguo]

What ✓ and × actually mean

• ✓ Accept means: “I have reviewed this relation and trust it for the current cached result.” It does not add a link to the note.
• × Ignore means: “Do not show me this machine suggestion again for now.” Understory stores a local ignore memory for that source-note / target-note pair, so the same candidate is filtered from later runs for 30 days.
• Insert means: “This belongs in my vault.” It writes a normal [[wiki link]] into the note, so it becomes part of your own Markdown structure.

So my practical rule is:

Use ✓ when you have reviewed a suggestion.
Use × when it is noise.
Use (or write the link yourself) when you want the relationship to survive as part of the vault.

Refreshing suggestions can replace machine-generated candidates, but it would NOT silently rewrite the connections you have chosen to maintain in Markdown.

One useful nuance: ignored suggestions are not banned forever. They can return after the ignore memory expires, which leaves room for a relationship to become relevant again as the vault changes.

I hope this makes the intended workflow clearer: the machine can keep looking, but it should not get to repeatedly overrule a decision you have already made.

[rosettaguo]

Understory Skill for Claude/Codex/OpenClaw/Hermes…

Understory 1.13.11 updates the paired Skill to make vault research more deliberate, inspectable, and useful.

How is this different from a normal AI vault query?

A normal vault query often starts and ends with matching notes or snippets. That is useful, but it can leave you to work out:

• Which sources are actually important
• What supports the answer versus what is only background
• What is missing from the vault
• What to read or do next

Understory’s Query-only Skill turns a broad question into a small research workflow:

1. Frame the question, intended reader, and desired output.
2. Search from 3–5 complementary angles, including synonyms or bilingual terms when useful.
3. Read scoped evidence through Understory’s local search, context, note-brief, and relation tools.
4. Curate the evidence instead of pasting back a raw result list.
5. Return a practical knowledge map: key assets, why they matter, gaps, and next actions.

The MCP provides scoped retrieval and relation signals from the current vault. The Skill provides the method for turning that retrieval into a useful answer.

---

What the output looks like

For a question such as “What do we already know about this product direction?”, the result should look more like this:

• Key assets: the notes, decisions, and references that matter most
• Why they matter: required reading, reusable insight, background, or needs verification
• Knowledge gaps: missing evidence, unresolved contradictions, and research blind spots
• Reading paths: different starting points for a PM, engineer, or researcher
• Next actions: the smallest useful follow-up investigation or decision

In other words: evidence and judgment, not just search results.

---

Control and privacy boundaries remain the same

The Understory MCP is a local, vault-specific stdio process—not an HTTP server. By default it returns scoped snippets rather than entire note bodies. The agent client and model you choose still have their own data policies, so those settings remain important.

The goal is not “AI that knows everything in the vault.” It is a clearer collaboration pattern:

Retrieve only what is relevant, show the evidence, identify uncertainty, and keep writes under user control.

I’d especially welcome feedback on what would make this more useful in practice: compact versus detailed maps, better output templates, or examples for product planning, research, and technical architecture.