README file from
GithubAdvanced Metadata Cache
Some of the questions Obsidian answers about a vault have no index behind them. Asking which notes link to this one means scanning every note, on every call — the Backlinks pane pays that cost, and so does every plugin that asks the same question. Asking what every note is called means the same walk, and the [[ autocomplete pays it every single time you open it. On a large vault it is slow enough to be felt.
This plugin maintains the indexes those questions deserve and answers from them instead. It does so by replacing the method that already asks the question, so nothing has to know the plugin is installed: the Backlinks pane gets faster, and so does anything else that asks.
Each index is a module that is switched on or off on its own, so a vault only pays for the ones it uses. On a small vault you will not notice any of them; that is the point at which you do not need this.
Demo vault
The documentation is an interactive demo vault. Every feature has a note that explains what it does and why you would want it, with buttons that measure the difference for real.
Start reading here — it is plain markdown, so it works on GitHub with nothing installed.
A copy of the vault ships with every release. You can access it via any of the following:
- Running the
Advanced Metadata Cache: Open demo vault command, on desktop. The command is not available on mobile, so use the next option there. - Downloading
advanced-metadata-cache-demo-vault.zipfrom the Releases. It unzips into a singleadvanced-metadata-cache-demo-vault-<version>folder. - Browsing its source in
demo-vault/in this repository.
What it does
- A backlink index that keeps itself current, so the Backlinks pane and every plugin that asks for backlinks stop rescanning the vault. 01 Backlink cache
- Three ways to ask — fast from the cache, safe after pending changes settle, or the original built-in implementation for comparison — and one more Obsidian has no call for: which notes link to a note that does not exist yet. 02 Fast, safe, and original backlinks
- Canvas files are indexed too, and so are frontmatter markdown links when
Frontmatter Markdown Linksis installed. 03 Canvas backlinks - A name index behind the
[[autocomplete, so opening it stops rescanning every note in the vault for its name and aliases. 05 Name index - A frontmatter property can name a note too, found under its
title, Quick switcher included, and, if you ask, offered under it by the[[autocomplete. Name patterns build a person's other names fromlastNameandfirstName, once per language, so none has to be stored as an alias. 06 Titles - When each heading was created, modified and seen, recorded per heading without touching the note, so other plugins can sort a note's headings by time. 07 Heading times
- Notes by frontmatter property value, dates kept in order, for other plugins to ask without scanning the vault, answered from disk at startup. 08 Property index
- Unlinked mentions without reading every note, so the Backlinks pane's Unlinked mentions section reads only the notes that mention the note, and lists exactly what it listed before. 09 Unlinked mentions
- A file answers to the texts links show for it, so
[alpha](bravo.md)lets other plugins findbravo.mdasalpha, and![[scan-0042.pdf|March invoice]]lets them find an attachment asMarch invoice. 10 Link texts - Links inside code blocks that are really notes, such as an
ad-noteadmonition, count like any other link once you list the block's language: in backlinks, outgoing links, the graph and rename updates. 11 Code block links - Which notes carry a tag, in their text or in their
tagsproperty, so other plugins find the notes tagged#project, nested tags included, without reading every note's cache. 12 Tags - Which notes link to a website, so other plugins can show a site's backlinks, suggest URLs the vault already uses and flag a host that looks like a typo, from every
httporhttpslink, bare, in a markdown link or in a property. 13 External links - Shared HTML source ranges and sanitizer checks let other plugins inspect markup without repeatedly parsing the vault. 15 HTML
- Properties for one heading or block, written in an
advanced-metadata-cachecode block right under it, the way frontmatter is written for the note, so other plugins can read them and find every block markedstatus: openacross the vault. 16 Block metadata - Metadata from other file types, such as Markdown links in
.mdxor.fountain, reaches core backlinks, graph link resolution and Bases property reads; plugins can register their own parsers. 14 Non-Markdown - Every index is a module of its own, switched on or off without touching the others; Backlinks, Properties, Link texts, Code block links and Non-Markdown are on by default. The last two read nothing until configured or registered by a plugin. A module switched off unloads completely. 04 Settings
Derived caches stay on each device; heading history and registered property names sync through ordinary vault files. See Storage and sync.
See also
| Plugin | Features | How Advanced Metadata Cache differs |
|---|---|---|
Backlink Cache (my plugin) |
Retired; points to its successor, which now carries the backlink index | Supersedes Backlink Cache: includes its backlink index; adds: names, titles, headings, properties, unlinked mentions |
Boost Link Suggestions |
Alternative wikilink suggester; link-count and manual-boost ordering | Same suggestion goal; keeps core suggester/order; indexed lookup instead of vault walks |
Datacore |
Reactive indexed query engine; JavaScript and JSX views | Different integration: accelerates core calls and their consumers; no query language |
Dataview |
Page/inline-field indexes; query language and JavaScript tables/lists/tasks | Different integration: core calls and startup-loaded property lookups; no query language |
Front Matter Title |
Frontmatter titles in explorer, tabs and graph | Complementary title lookup: finds notes by title; offers titles in autocomplete; no display changes |
Vault Map |
JSON Lines export of frontmatter, links, embeds and backlinks | Alternative index access: in-memory core calls and plugin API; no export file |
Last searched for similar plugins on 2026-10-26.
For plugin developers
This plugin makes two core calls faster for every plugin that makes them, and publishes an API, declared in api.d.ts, for what core has no call for. The member-by-member reference is docs/api.md.
app.metadataCache.getBacklinksForFile(file) (the Backlinks module) and app.metadataCache.getLinkSuggestions() (the Names module) keep Obsidian's own signature and answer what Obsidian would, so there is nothing to do to use them.
Everything else (the safe, original and reverse-lookup variants of those two calls, titles, heading times, notes by property value or date, unlinked mentions, link texts, notes by tag, external links, HTML candidates and diagnostics, and the code block languages whose links count) is AdvancedMetadataCacheApi:
import { watchPluginApi } from '@mnaoumov/obsidian-lib/plugin/plugin-api';
import type { AdvancedMetadataCacheApi } from './api.d.ts';
import { ADVANCED_METADATA_CACHE_API_CONTRACT } from './api-contract.ts';
const apiRef = watchPluginApi<AdvancedMetadataCacheApi>({
apiVersionRange: '^1.3',
app: this.app,
component: this,
contract: ADVANCED_METADATA_CACHE_API_CONTRACT,
pluginId: 'advanced-metadata-cache'
});
// `value` is always current and never stale: `null` while this plugin is not loaded, and non-`null`
// on its own once it is.
const api = apiRef.value;
if (api) {
console.log(api.getTitles('Notes/Some note.md')); // ['The Real Name']
}
The handle comes from the @mnaoumov/obsidian-lib plugin registry; Cross-plugin APIs covers watchPluginApi and the registry from the library's side. The contract version moves independently of the plugin's own, so ask for a range, and ask for the lowest version that has every member you call; the reference says which version each one arrived in.
If you would rather not depend on @mnaoumov/obsidian-lib for the handle, the registry is a documented wire protocol you can read directly — see Plugin API protocol.
Installation
The plugin is available in the official Community Plugins repository.
Beta versions
To install the latest beta release of this plugin (regardless if it is available in the official Community Plugins repository or not), follow these steps:
- Ensure you have the BRAT plugin installed and enabled.
- Click Install via BRAT.
- An Obsidian pop-up window should appear. In the window, click the
Add pluginbutton once and wait a few seconds for the plugin to install.
Debugging
By default, debug messages for this plugin (id: advanced-metadata-cache) are hidden.
If you need to enable them refer to the documentation.
Changelog
All notable changes to this project will be documented in the CHANGELOG.
Contributing
Contributions are welcome — see CONTRIBUTING to get set up.
Support
Filing an issue (for AI agents and humans)
Open issues through the issue forms, not as blank issues.
To report a bug from inside Obsidian, run the Advanced Metadata Cache: Report a bug command. It opens the bug form with the plugin version, the Obsidian version and your operating system already filled in.
Filing from the CLI or the API (gh issue create --body, or an AI agent filing for you) skips the form, and gh issue create --template cannot load an issue form. In that case, open the matching form in .github/ISSUE_TEMPLATE/, copy every field as a ### <label> heading in the form's order, and fill in each one. Always state the plugin version, the Obsidian version and your operating system.