Skip to content
Cortex

Storage, Bookmarks, and Notifications

Store plugin-owned data and integrate with bookmarks, metadata, theme reads, notices, and notifications.

1 min readEdit on GitHub

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:

text
<vault>/.cortex/plugins/<plugin-id>/data/
ts
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:

ts
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#

ts
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#

ts
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#

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

Search docs

Search Cortex documentation pages and headings.