Set up notegraph: a guide for AI assistants
On this page
This page is for an AI assistant that a person asked to set up notegraph. If you are that assistant, follow the steps in order and do not skip the checks. If you are a person, you can read along, or install it yourself.
What you are setting up#
notegraph is a private notebook on the user's own computer. You read and write its notes through sixteen tools, over MCP (the Model Context Protocol, the standard way an AI app connects to a tool). Each change you make is saved at once, with your name, the time and the computer. The user sees every change in a log and can undo any of them. There is no account, no server and no login.
In this setup you do five things, and you leave three to the user.
- You do: check the computer, install notegraph, make the vault, register the MCP server, check that it works.
- The user does, later, in their own terminal: bring in the notes of an obsidian vault; turn on sync between the user's computers; hide a folder from every assistant.
- You never: read the data folder of notegraph, read its keys, or run a command from the list in What only the user can do.
Step 1. Check the computer#
Run
node --version
It worked if the output is v20 or later. notegraph runs on macOS and Linux. On
Windows, stop and tell the user that Windows is not supported in this version. If Node.js is missing or older than
20, stop and ask the user to install Node.js 20 or later. Do not install it for them without asking.
Step 2. Install notegraph#
Run
npm install -g notegraph
Then check
notegraph --version
It worked if the output starts with notegraph and a version number. This guide is for
version 0.0.0. If npm says that the package does not exist (E404), notegraph
is not released: say so and stop.
Step 3. Make the vault#
Run
notegraph init
It worked if the output is Vault is ready at and a folder. The vault is the place
where notegraph keeps the notes and their history. If the output says that a vault already exists, keep it. Do not
make a second one and do not delete anything.
Step 4. Register the MCP server#
Register notegraph in the AI app that the user works in. The command pins the version, so the app runs the version that the user chose. More detail is on the MCP clients page.
Claude Code#
Run
claude mcp add notegraph -- npx -y notegraph@0.0.0 mcp
Then check
claude mcp list
It worked if the list has a line for notegraph.
Claude Desktop#
Add the notegraph entry to claude_desktop_config.json. On macOS the file is in
~/Library/Application Support/Claude/. Keep every other server that is in the file. Then ask the user
to quit and open Claude Desktop again.
claude_desktop_config.json
{
"mcpServers": {
"notegraph": {
"command": "npx",
"args": [
"-y",
"notegraph@0.0.0",
"mcp"
]
}
}
}
It worked if the file is valid JSON and has the entry. You cannot see the result yourself: the user sees the notegraph tools after the restart.
Another AI app#
The docs cover Claude Code and Claude Desktop only. For another app that speaks MCP, put the command
npx -y notegraph@0.0.0 mcp in that app's own settings, and tell the user that this app is not covered by the docs.
Step 5. Check that it works#
Run
notegraph status
It worked if the output has a line that starts with Notes. A new vault has 0 notes.
An AI app loads its MCP servers when a session starts, so you may not have the notegraph tools in this session.
That is normal. Do not try to reach the notes another way.
Step 6. Tell the user#
Finish with a short report in plain words. Say these things:
- What you installed, and the version that
notegraph --versionprinted. - Where the vault is: the folder that
notegraph initprinted. - Which AI app you registered it in, and that they must start a new session (Claude Code) or restart the app (Claude Desktop).
- What they can ask you now, for example:
Save this as a note in my Clients folder.
What did I write about the Lisbon trip?
Add oat milk to my shopping list.
- That every change you make is saved at once, and that they see and undo changes with
notegraph login their own terminal. - The three things only they can do, each with its command (the next section).
Then offer one more step: rules that keep your shell and file tools away from notegraph, so that you reach the notes only through the MCP tools. The rules are on the MCP clients page. Add them only if the user says yes.
What only the user can do#
These commands refuse to run inside an assistant's shell. The refusal reads
does not run inside an agent shell. That is by design, not a fault to work around. The check knows the
shell of Claude Code and may not know yours, so do not run these commands even when your shell lets you. Give the
user the command and the reason.
| The user wants to | Command | Why you must not run it |
|---|---|---|
| Bring in the notes of an Obsidian vault | notegraph import <folder> |
It records every imported note as a change made by the user. An assistant must not write in the user's name. |
| Turn on sync between the user's computers | notegraph sync setup |
It makes and shows the keys and the recovery phrase of the vault. They must not reach an assistant. |
| Hide a folder from every assistant | notegraph deny add <folder> |
The user decides what an assistant may see. An assistant must not change its own limits. |
| Add another computer to the vault | notegraph pair |
It handles the keys of the vault. |
| Back up the vault to a file | notegraph backup <file> |
The file holds a copy of every note, the ones in hidden folders too. |
| Replace the vault with a backup | notegraph restore <file> |
It replaces every note and the whole history. |
| Edit a note in the user's own editor | notegraph open <note> |
It records the edit as a change made by the user. |
| Undo changes from the command line | notegraph revert <change> |
It records the undo as made by the user. To undo a change yourself, use the revert tool, which records it as yours. |
The interactive view of notegraph log also needs the user's own terminal. To see what changed, use the
history tool.
When a step fails#
- npm cannot find the package (
E404). notegraph is not released. Say so and stop. - Node.js is missing or too old. Stop and ask the user to install Node.js 20 or later.
-
npm has no permission to install (
EACCES). Do not usesudo. Show the error to the user and ask how they install global npm packages on this computer. -
The shell cannot find
notegraphafter the install. The folder of global npm programs is not on the path. Runnpm prefix -g, show the user the result, and ask them to add itsbinfolder to their path. -
A command says
does not run inside an agent shell. It is one of the commands above. Hand it to the user. - Anything else. Stop. Show the user the exact command and the exact error. Do not try other flags, do not delete the data folder, and do not install from another source.