What stays private
On this page
notegraph runs on your machines. It has no server, no account and no telemetry. This page says what stays where, and what notegraph cannot stop.
What stays on your device#
Your notes and their full history live in a local store. The history keeps the text of notes you deleted and of passages you replaced. The store is not encrypted on disk. Your keys are in the OS keychain, or in a file if you chose that.
What goes to your bucket#
Nothing, until you run notegraph sync setup or notegraph pair. After that, ciphertext goes to
the bucket you named, over HTTPS (an http endpoint is accepted only on a loopback address), and nowhere else. The keys never go with it. The provider of the bucket can see the
vault ID, the device IDs, the number and size of the objects, their upload times and the IP address of each device.
See what the bucket sees.
What your MCP client sends to its model provider#
When an agent calls read, search or history, notegraph returns note text to your
MCP client. The client sends it to its model provider as part of the conversation. notegraph does not control that and
cannot see it. Choose a client and a provider you trust with the notes the agent can reach.
notegraph itself opens no network port. The only connection it makes is to your bucket. The MCP layer writes one line to its own standard error for each tool call: the tool name, the outcome, the time taken and the change ID. The line has no path, no query and no note text.
The deny list#
notegraph deny add Private/
A denied folder is invisible to every agent tool. read, write and the others refuse it with
forbidden_path, search, backlinks and graph never return it, and
history hides its changes. deny add and deny remove need your own terminal, and
deny list shows the list. The deny list syncs to your other devices. It stops the notegraph tools. It does
not stop an agent that reads files itself.
What notegraph cannot stop#
notegraph does not defend against a program that runs as you. If an agent has a shell tool or a file tool in your account, it can:
- read the store, which holds every note and its history, and change it without a recorded change;
- ask the OS secret store for your keys, or read
secrets.keyif you use one; - run
notegraphcommands.
The commands that record a change as you or touch your keys (revert, open,
deny add and deny remove, restore, pair and
sync setup, sync credentials and sync rotate) refuse to run when stdin or stdout
is not a terminal, and when the CLAUDECODE marker is set in the environment. That stops a careless
attempt. A program that fakes a terminal or unsets the marker gets through. The marker covers Claude Code only. For any
other client, only the terminal check applies.
The tools that notegraph gives an agent are limited by design: no sync, no keys, no import, no deny list, no way to write as you or to purge history. Limit the rest with your client.
Client permission rules#
The MCP tools are the way an agent should reach your vault. These rules keep its shell and file tools away from the command line, the store and the secrets. Add them to the settings of your client. This example uses the rule syntax of Claude Code; other clients have their own.
Claude Code settings.json
{
"permissions": {
"deny": [
"Bash(notegraph:*)",
"Bash(npx notegraph:*)",
"Bash(npx -y notegraph:*)",
"Bash(sqlite3:*)",
"Bash(security:*)",
"Bash(secret-tool:*)",
"Read(~/Library/Application Support/sh.notegraph/**)",
"Edit(~/Library/Application Support/sh.notegraph/**)",
"Read(~/.local/share/notegraph/**)",
"Edit(~/.local/share/notegraph/**)"
]
}
}
notegraphandnpx notegraphare the command line, which can revert, open and change what agents may see.-
The data directory holds the store and, if you chose a file for your keys,
secrets.key. It is~/Library/Application Support/sh.notegraphon macOS and~/.local/share/notegraphon Linux, unlessNOTEGRAPH_HOMEis set. sqlite3opens the store directly.security(macOS) andsecret-tool(Linux) read the OS secret store.
Read-only mode#
Start the server with mcp --read-only for any session where the agent reads web pages or other text you do
not control. A note, a page or a file can carry instructions meant for the agent. In read-only mode the agent can read
and search, and it cannot write. See the config.
Rotate a pasted credential#
If you pasted a password, a token or a key into a note, treat it as seen by every agent that could read that note, and by every device that syncs. Deleting the text from the note does not remove it. The history keeps it, and this version of notegraph has no way to purge it. Change the credential at its source: rotate the token, set a new password. Then delete it from the note. If it was your bucket token, follow the steps for a lost device.
Plain copies of your notes#
notegraph does not write a Markdown copy of your vault in this version. If you write one yourself, for example with
notegraph show <note> --raw > note.md, treat the file as plain text in the open. The deny list does
not apply to it, an agent with a file tool can read it, and a change to it is not recorded. Do not open such a folder in
a tool that runs code from notes, such as an editor with scripting plugins.
Full-disk encryption#
The store, its history, the backups you make and the key file (if you use one) are plain files. Turn on full-disk encryption on every machine that holds a vault: FileVault on macOS, LUKS on Linux. Without it, a lost laptop gives a thief your notes.
Pin the npx command#
npx -y notegraph@0.0.0 mcp
Put the version number in the command that starts the server. Without it, npx can fetch a newer release than the
one you checked, and a false copy of the package or a bad release would run in your account. Check that the
name is notegraph and take commands from this site.