The path of one read

  1. Your AI app

    Calls a tool, for example search_memories.

  2. Connector, on your computer

    Derives its token from the app key and asks the server for the folders this app may read.

  3. Sigil's server

    Checks the token, writes the request to your read log, and answers with ciphertext.

  4. Connector, on your computer

    Unwraps the folder keys, decrypts, searches by words and by meaning locally, and hands plain text to the app.

Install

Nothing to install

Your AI app starts the connector with npx -y sigil-connector. It needs Node.js 20 or newer.

Then add it to your app. The block on the right is the form most MCP apps take; each app's exact file is on the Apps page.

MCP configuration
{
  "mcpServers": {
    "sigil": {
      "command": "npx",
      "args": [
        "-y",
        "sigil-connector"
      ],
      "env": {
        "SIGIL_APP_KEY": "sigil_app.<app id>.<secret>",
        "SIGIL_URL": "https://sigilvault.fun"
      }
    }
  }
}

Four tools that read, one that suggests, one that answers as you

The tools that read and ask_self are marked read only for the AI app. The answers below are the plain text an app receives, in the connector's own format.

get_profile

Your Self card: who you are, how you like answers and what you are working on. The app is told to call it first. Works only if it may read the Self card folder.

Takes no arguments.

In your read log The app read the index, then the card.

What the app receives
# Self card
Edited: 2026-11-20

## Who I am

A designer who builds boats on weekends.

## How I like answers

Short, plain words, metric units.

list_folders

The folders this app may read, with how many memories each holds.

Takes no arguments.

In your read log The app listed its folders.

What the app receives
Folders this app can read:
- Work (42 memories)
- Writing (17 memories)

search_memories

Searches by meaning and by the words in titles, tags and first lines, on your computer: a question about your car finds the note about the garage. An empty query lists the most recent. Returns ids for read_memory.

query
Words to look for, up to 500 characters. Empty for the most recent.
folder
Optional. Only search this folder, by name.
limit
Optional. 1 to 50 results, 10 by default.

In your read log The app read the index of N memories. The search words are not sent.

What the app receives
2 memories match "launch":

1. Launch plan
   id: 9fK2mQx7Lw3d | folder: Work | tags: work | edited 2026-11-19
   Ship on a Tuesday.

2. Release checklist
   id: 4Qa8NcT1pZ0e | folder: Work | edited 2026-11-12 | matched by meaning
   Freeze the build two days before.

These are the first lines only. Call read_memory with an id for the full text.

read_memory

The full text of one memory, by the id from search_memories.

id
The memory id.

In your read log The app read that memory.

What the app receives
# Launch plan
Folder: Work
Tags: work
Source: Written in Sigil
Created: 2026-11-19 | Edited: 2026-11-19

Ship on a Tuesday.

propose_memory

Suggests a memory to your inbox. It is sealed on your computer for your vault, and becomes a memory only when you approve it. Works only if you let this app suggest.

title
A short title, up to 300 characters.
body
The memory, in plain words.
tags
Optional. Up to 12 tags.
folder
Optional. The folder the app suggests, by name. You decide.

In your read log The app suggested a memory.

What the app receives
Suggested "Prefers metric units" to the user's Sigil inbox. It becomes a memory only if they approve it.

ask_self

Asks your AI self: it answers as you, in the first person, only from the folders your rules allow that this app may also read, with your own model key, on your computer. Works only if you let this app answer as your AI self.

question
The question, up to 2,000 characters.

In your read log The app read the memories it used, and your AI self answered a question (sealed for your vault).

What the app receives
Short answers, plain words and metric units, please [1].

From: How I like answers (Self card)

Five more for an agent key

When the key belongs to an agent vault, the connector notices at start and adds tools for the agent's own memory. The owner sets a switch for each, and the server enforces it on every call.

remember

Writes a memory to the agent's own folder, or to a folder or team space it may write. Encrypted on your computer.

In your read log The agent remembered that memory.

What the agent receives
Remembered "Parser state" in Cursor memory (id 7Rk2pWq9Lm4c).

recall

Finds what the agent may read, its team spaces included, by meaning and words on your computer, and returns the best matches in full.

In your read log The index, and each memory read.

What the agent receives
1. Parser state
   id: 7Rk2pWq9Lm4c | in Cursor memory | edited 2026-11-20

Half done: tokens work, the tree does not yet.

forget

Deletes memories by id, for good, only where the agent may write. Off until the owner allows it.

In your read log The agent forgot that memory.

What the agent receives
Forgot 1 memory.

leave_handoff

Leaves an encrypted note for the agent's next session, or for the other agents in a team space.

In your read log The agent left a handoff note.

What the agent receives
Left a note for this agent's next session.

pick_up_handoffs

Returns the notes waiting for the agent and marks them picked up. Agents are told to call it first.

In your read log The agent picked up a handoff note.

What the agent receives
From cursor, 2026-11-20:
Next: wire the parser into the CLI.

Setup for Claude Code, Cursor, VS Code and other clients is in the docs.

Four ways to run it

Stdio

Started by the app

Claude Desktop, Claude Code, Cursor, Windsurf, VS Code and most MCP apps start the connector themselves and talk to it over standard input and output. Nothing listens on the network.

Terminal
SIGIL_APP_KEY=sigil_app.<app id>.<secret> \
SIGIL_URL=https://sigilvault.fun \
npx -y sigil-connector
HTTP

Served at a private address

For apps that only take a URL, such as ChatGPT. The connector serves /mcp/<token> on your machine. Anyone who has the full address can read what the app key can read, so keep it private.

Terminal
SIGIL_APP_KEY=sigil_app.<app id>.<secret> \
SIGIL_URL=https://sigilvault.fun \
SIGIL_HTTP_TOKEN=<a long random string> \
npx -y sigil-connector --http --port 8787
Self

Answering your ask links

With --self it answers the ask links you gave this app, and your public AI self when you picked this app for it, while your vault is closed. Questions arrive sealed, are answered on your machine with your own model key, and go back sealed. They show as online while it runs.

Terminal
SIGIL_APP_KEY=sigil_app.<app id>.<secret> \
SIGIL_URL=https://sigilvault.fun \
npx -y sigil-connector --self
Watch

Live sync and Obsidian

With --watch it keeps the live sync sources you gave this app (Gmail, Calendar, Drive, Slack) in sync while your vault is closed, every few minutes, encrypting on your machine. With a folder too, it watches an Obsidian vault and suggests new and changed notes to your inbox; a small file in your home folder remembers what was sent, as hashes only.

Terminal
SIGIL_APP_KEY=sigil_app.<app id>.<secret> \
SIGIL_URL=https://sigilvault.fun \
npx -y sigil-connector --watch ~/Obsidian

Settings

SettingMeaning
SIGIL_APP_KEYRequired. The app key from your vault. It starts with sigil_app. Keep it private: it can read the folders you granted.
SIGIL_URLRequired. The address of the Sigil site your vault lives on, for example https://sigilvault.fun.
SIGIL_HTTP_TOKENHTTP mode only. The secret last part of the address, 16 to 128 letters, digits, - or _. A random one is made when unset.
SIGIL_SEMANTICSearch by meaning on your computer. On unless set to off.
SIGIL_EMBED_MODELThe sentence model for search by meaning. Xenova/all-MiniLM-L6-v2 by default, about 23 MB.
SIGIL_MODEL_DIRWhere the model files are kept. .data/models in the repository, or ~/.sigil/models elsewhere.
SIGIL_MODEL_FETCHFetch missing model files once from the public model hub. Set to off to use only files already on disk.
--httpServe over HTTP instead of stdio.
--port, --hostHTTP mode only. Default 8787 on 127.0.0.1.
--help, --versionPrint the usage, or the version.

What it does not do

It does not write your memories

No tool or endpoint lets an app change or delete a memory. A suggestion, a synced note included, waits in your inbox, sealed, until you approve, merge or reject it.

It does not remember

Each request fetches and decrypts afresh, so a revoked key stops working on its very next request.

It does not send your search

Search, by words and by meaning, runs on your computer over the decrypted index. The server only learns that the index was read.