Skip to main content
Glama

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 entries

  • remember(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 pair

It 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-mcp afterwards

  • OpenCode: 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:7303

Agents 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 command

write/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 machine

Open http://<host>:7300/app to create an account in the browser.

  • Your data is the --db file (default ~/.vortex-notes/relay.db). Back it up. --db :memory: is for throwaway tests.

  • Chat apps (Claude, ChatGPT):

    • Set RELAY_CONNECTOR_KEK to 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-Host headers, so a reverse proxy just works.

  • Other settings:

    • RELAY_QUOTA_MB caps 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 tools
append_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 contextA
Read-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 noteA
Destructive

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 notesB
Read-only

List note paths, optionally under a folder.

Inputs: limit, folder.

read_noteRead noteA
Read-only

Read a note's full markdown content by vault-relative path.

Inputs: path (required).

recent_activityRecent activityB
Read-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 notesA
Read-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

    A3.6/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-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.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Portable 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to capture, structure, remember, and retrieve source-backed memory as local Markdown files, with reviewable writes and no cloud dependency.
      220
      MIT