Storage, Bookmarks, and Notifications
Store plugin-owned data and integrate with bookmarks, metadata, theme reads, notices, and notifications.
These APIs integrate plugins with host-owned data, user bookmarks, metadata, themes, and native
notifications. Each one requires a runtime permission in manifest.permissions.
Plugin Data#
Plugin data is vault-scoped and stored under the plugin directory:
<vault>/.cortex/plugins/<plugin-id>/data/await ctx.data.write("cache.json", JSON.stringify({ lastRun: Date.now() }))const cached = await ctx.data.read("cache.json")await ctx.data.delete("cache.json")Requires data. Filenames must not contain .. and must not start with / or \.
Use data files for plugin-owned state and caches. Use vault APIs for user-visible notes. Settings are separate and need no permission (see Views, Settings, and UI).
Metadata#
Metadata APIs require vault:read:
const frontmatter = await ctx.metadata.getFrontmatter("Projects/Plan.md")const tags = await ctx.metadata.getTags("Projects/Plan.md")const allTags = ctx.metadata.getAllTags()Metadata paths are vault-relative Markdown paths.
Bookmarks#
const bookmarks = ctx.bookmarks.list()await ctx.bookmarks.toggle("Projects/Plan.md")const isBookmarked = ctx.bookmarks.isBookmarked("Projects/Plan.md")Reads require bookmarks:read. Mutations require bookmarks:write. Bookmark paths are
vault-relative Markdown paths.
Theme Read API#
const activeTheme = ctx.theme.getActiveThemeName()ctx.theme.onThemeChange((name) => console.log("Theme changed", name))Requires theme:read. Plugins observe the active theme name; they do not mutate themes. The
subscription is disposed automatically when the plugin is disabled.
Notifications and Notices#
const result = await ctx.notifications.send({ title: "Task complete", body: "Your plugin finished processing notes.", kind: "success",})if (!result.delivered) { console.warn(result.reason)}Requires notifications; without it, send resolves
{ delivered: false, reason: "missing-capability" }. Plugins cannot request OS notification
permission directly; Cortex owns permission prompts and platform support.
ctx.ui.showNotice(message) also requires notifications and is delivered through the host notice
path.
Notifications are rate-limited per plugin. Keep them user-meaningful and avoid sending repeated status spam.