Vortex Notes
Use this MCP server to search, read, write, and maintain a Vortex Notes vault as agent memory.
Search notes with hybrid keyword + semantic search, or keyword-only, with configurable result limits.
Read a note’s full markdown content by vault-relative path.
Create new notes with title, content, optional folder, and tags; fails if the path already exists.
Edit existing notes surgically via append, prepend, or exact find/replace.
Append timestamped entries to today’s daily note or a specified date.
Build topic context in one call: top matching notes in full plus one hop of
[[wikilinks]].Record durable facts in
memory/*.md, optionally superseding older facts while keeping them visible and struck through.List recently modified notes and list note paths, optionally within a folder.
Vortex Notes
End-to-end-encrypted notes that double as memory for your AI agents.
Your notes are plain .md files you own — greppable, git-able, Obsidian-compatible.
Vortex Notes adds the two things a notes app and an agent-memory store each do
separately, in one place:
The server can't read anything. A 12-word phrase is your whole account; keys are derived in your browser. The relay stores ciphertext only — no plaintext field exists in its schema, and there's no password to reset because there's nothing on the server to reset.
Agents are principals, not passengers. An agent gets its own key — born on its machine, never transmitted, certified by yours, scoped to the spaces you grant, and revocable in one command. Every edit it makes is signed as the agent.
That combination — agents can fully use it and the server can't read it — is the empty quadrant this fills.
The app
A real app, not a viewer: installable on iPhone / Android / Mac (works offline), sub-second cross-device sync over WebSocket, and an Obsidian-style live-preview markdown editor that's as good on a phone as on a desktop.
Password-locked notes — lock a note with a password or your 12 words; the title stays visible, the body is a sealed second layer even your own devices can't read until unlocked.
Version history & recovery — every synced version is kept; restore an earlier one, or recover a note whose password you lost from before it was locked.
Public notes — publish any note to a themed public page in one tap.
Change your 12 words — rotate your recovery phrase without losing a thing; every signed-in device and agent keeps working, the old phrase goes dead.
Related MCP server: Citadel
Agent memory (MCP)
A first-party MCP server gives Claude Code, OpenClaw, Cursor, or any MCP client task-shaped tools — not a CRUD mirror — and it works headless:
search_notes·read_note·write_note·edit_note(surgical)append_daily— timestamped journal entriesremember(fact, supersedes)— facts with a lifecycle: a superseded fact stays visible, struck through, pointing at what replaced it. Auditable, not a black box.build_context(topic)— the top notes in full plus one hop of[[wikilinks]], so an agent starts a task with the right context in one call.
Search is on-device. Hybrid BM25 + multilingual embeddings (SQLite FTS5 + sqlite-vec + a small local model). No API key, nothing leaves your machine, and an English query finds your Spanish notes across ~100 languages.
Quick start
Try the app
Open vortex-notes.pages.dev/app, create an account (save the 12 words), and start writing. Add it to your home screen to install it. That's the whole onboarding — no email, no password.
Connect an agent
On the agent's machine:
npx -y vortex-notes@latest pairIt prints a 6-letter code; approve it in the app (user menu → Agents & devices →
Pair an agent). The agent gets its own scoped, revocable key and never sees your
recovery phrase. pair then wires every harness it finds on that machine, pinned
to the paired vault:
Claude Code: user scope, so every project sees it
Hermes: type
/reload-mcpafterwardsOpenCode: added to
~/.config/opencode/opencode.json
No MCP in your agent? The same tools work as shell commands, see
Agents without MCP.
Works over SSH too (you approve from your phone). Any other stdio MCP client:
{ "command": "npx", "args": ["-y", "vortex-notes", "mcp"], "env": { "VORTEX_NOTES_VAULT": "<path pair printed>" } }.
Add --read-only to make it read-only.
Connect Claude.ai, ChatGPT, or another chat app
Chat apps in the browser or on your phone can only reach an MCP server by URL. In the app: user menu → Agents & devices → Connect a chat app creates a cloud agent and gives you a secret connector URL:
Claude (web, desktop, mobile): Settings → Connectors → Add custom connector → paste the URL
ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode → Create → paste the URL (no authentication)
This is the one opt-in exception to zero-knowledge: the relay holds that agent's key (encrypted at rest) so it can serve the notes that agent may access. It's scoped, can be read-only, and revoking it kills the URL. Everything else stays end-to-end encrypted.
Use the CLI
npm install -g vortex-notes
vortex-notes init # create a vault
vortex-notes search "that idea about pricing" # hybrid semantic + keyword
vortex-notes serve # local web viewer at 127.0.0.1:7303Agents without MCP: the same tools as commands
Every MCP tool is also a command, so any agent that can run a shell (OpenClaw-style
harnesses, scripts, cron, git hooks) gets the same behavior. After pair, commands
find the paired vault by themselves; each one syncs before reading and after writing.
npm install -g vortex-notes@latest # once, so `vortex-notes` is on PATH
vortex-notes context "kiln" # top notes in full + linked notes
vortex-notes read projects/kiln.md
vortex-notes daily "fired the test tiles"
vortex-notes remember "Kiln max is cone 8" --topic kiln --supersedes "cone 10"
vortex-notes write "Glaze tests" "Three recipes…" --folder studio --tags glaze
vortex-notes edit clay.md --append "Order more in May."
vortex-notes recent --days 3 --json # --json on any commandwrite/edit/daily/remember read stdin when the text is -. Errors exit 1
({"error": …} with --json). Full list: vortex-notes --help. There's a ready
OpenClaw skill built on these.
The index in .vortex/index.db is disposable — the markdown files are always the
source of truth. VORTEX_NOTES_NO_SEMANTIC=1 skips embeddings (keyword only, no
model download).
Self-host the relay
The hosted relay at vortex-notes.pages.dev is convenience, not lock-in. Run your own:
vortex-notes relay --port 7300 --db ~/relay.db # the ciphertext store, web app and chat connectors
vortex-notes setup --relay http://<host>:7300 # on each computer: your 12 words, then sync
npx -y vortex-notes@latest pair --relay http://<host>:7300 # an agent machineOpen http://<host>:7300/app to create an account in the browser.
Your data is the
--dbfile (default~/.vortex-notes/relay.db). Back it up.--db :memory:is for throwaway tests.Chat apps (Claude, ChatGPT):
Set
RELAY_CONNECTOR_KEKto 64 hex characters (openssl rand -hex 32) before creating connectors, so their keys are encrypted at rest.Serve the relay over HTTPS (Caddy, nginx, or a tunnel): the chat apps can't reach
localhost.OAuth discovery follows the
Host/X-Forwarded-Hostheaders, so a reverse proxy just works.
Other settings:
RELAY_QUOTA_MBcaps each account's storage.RELAY_ADMIN_ACCOUNT(your Account ID) turns on admin stats in the web app.
Native apps: the Mac and iPhone apps use the hosted relay for now. The CLI, agents and the web app work with any relay.
How the encryption works
A 12-word BIP39 phrase derives your account's signing + encryption keys. Each
device and agent has its own random keypair, certified by your account key — an
account → device → agent chain. A space's content key is sealed to each
principal that may read it; the relay enforces scope and read-only on every signed
request but only ever holds sealed blobs.
What a malicious or subpoenaed relay can do: serve stale or withheld ciphertext (detectable via sequence gaps). What it can't do: read a note, a title, or a key; forge an edit; or silently alter one. The WebSocket sync channel carries only content-free "a space changed" pokes — the doorbell, never the data.
For a broad usage view, the relay derives a coarse country (two-letter code) from your IP in memory and stores only that code — the IP itself is never written to disk or logged.
Stack
TypeScript, all-MIT: @noble /
@scure crypto, CodeMirror 6,
better-sqlite3, sqlite-vec, transformers.js,
marked. The relay is a small Node service; the web app is a single esbuild bundle
with all crypto client-side. 48 unit tests plus ten Playwright browser suites.
MIT © Vortex303
Available Tools
9 toolsappend_dailyAppend to daily noteA
Append a timestamped entry to today's daily note (or a given date). The right place for observations, decisions, and things to remember.
Inputs: content (required), date.
build_contextBuild contextARead-only
Load working context for a topic in one call: full content of the top-matching notes plus one hop of [[wikilinked]] notes as pointers. Prefer this over multiple search+read rounds when starting work on a topic.
Inputs: topic (required), max_notes.
edit_noteEdit noteADestructive
Edit an existing note surgically: append, prepend, or find_replace (exact string). Prefer this over rewriting whole notes.
Inputs: path (required), content (required), operation (required), find.
list_notesList notesBRead-only
List note paths, optionally under a folder.
Inputs: limit, folder.
read_noteRead noteARead-only
Read a note's full markdown content by vault-relative path.
Inputs: path (required).
recent_activityRecent activityBRead-only
List notes modified in the last N days, newest first.
Inputs: days, limit.
rememberRemember a factA
Record a durable fact in the shared memory (memory/*.md) as a dated bullet with a stable ^id. If it replaces an earlier fact, pass supersedes (the old fact's ^id, or a distinctive substring of it) — the old fact stays visible with strikethrough and a pointer to the new one. Use search_notes to find existing facts first.
Inputs: fact (required), topic, supersedes.
search_notesSearch notesARead-only
Search the vault with hybrid keyword + semantic search. Returns note paths, headings, and snippets. Use read_note for full content.
Inputs: query (required), mode, limit.
write_noteCreate noteA
Create a new markdown note. Fails if the path already exists — use edit_note to modify existing notes.
Inputs: title (required), content (required), tags, folder.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a fairly distinct purpose, and descriptions explicitly steer between near-neighbors (write_note vs edit_note, search_notes vs build_context). The main soft overlap is the family of write paths — write_note, edit_note, append_daily, and remember all add content to different targets — but the docs make the targets clear enough that misselection is unlikely.
Most tools follow a clean verb_noun pattern (search_notes, read_note, write_note, edit_note, build_context, list_notes). Two outliers — the bare verb 'remember' and the adjective-style 'recent_activity' — break the pattern but remain readable and unambiguous.
Nine tools is well-scoped for a note vault server, covering discovery, reading, writing, memory, and recency without redundancy. Every tool maps to a genuine workflow step; nothing feels padded or missing at the count level.
The surface covers search, read, create, surgical edit, daily append, durable memory, and recency, which handles most agent workflows. However there is no delete, move, or rename operation, so note lifecycle management is a dead end once a note is created at the wrong path or needs removal.
Maintenance
Related MCP Connectors
Memory for Claude, ChatGPT and other AI apps: notes and docs as a searchable graph, EU-hosted.
Encrypted long-term memory shared across your AI assistants (Claude, ChatGPT, Perplexity).
One memory for Claude, ChatGPT and Cursor, kept on your computer. Optional sync, encrypted first.
Portable AI memory you own. Keep memories and notes across Claude, ChatGPT, and other AI tools.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLocal-first, file-based memory layer for AI agents — one shared Markdown vault across Claude, Codex, Gemini, Cursor and any MCP client. Provides read/write memory tools with an audit trail, per-agent trust levels, and Git sync; no cloud and no lock-in.2MIT
- AlicenseNot gradedqualityBmaintenanceLocal-first, encrypted memory for AI agents, with cryptographic forgetting.643 PyPI4Apache 2.0
- AlicenseNot gradedqualityBmaintenancePortable AI memory that roams with you across models and harnesses — one shared memory for Claude Code, Codex, Cursor, Gemini CLI and more, stored as plain markdown files you own. Per-project spaces plus a shared layer, vault-wide search; runs locally over stdio/HTTP or hosted with OAuth 2.1 backed by your own GitHub repo.33 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to capture, structure, remember, and retrieve source-backed memory as local Markdown files, with reviewable writes and no cloud dependency.220MIT