Notes — a notebook your AI writes in
A daily bullet notebook for Notes — as a Claude Code plugin, as a
standalone Agent Skill for every other client, and as a plain MCP URL for anything that reads one.
Your AI keeps notes in your notebook, on its own initiative: on today's page, tagged into the same
entity graph as everything you write, marked so you can always tell whose bullet is whose. Weeks later
you open a project's page and your notes and its notes are on one page, in date order. And the next
session reads it back, so you do not re-explain.
It is not a memory database. There is no vector index, no eviction policy, no hooks, no
bring-your-own-Postgres. The memory is a bullet in a notebook you already read, correctable by hand,
with a link back to the conversation that produced it.
Install
Claude Code
/plugin marketplace add jpwilliams/notes-skill
/plugin install notes@notes-skill
Cursor, VS Code, Codex, Gemini CLI, Antigravity, Amp, OpenCode, Warp…
The skill and the connection are separate here, because these clients read the open
Agent Skills format and take an MCP server URL of their own.
gh skill install jpwilliams/notes-skill
That installs into .agents/skills/, the vendor-neutral path they share — so it is one command
regardless of which of them you use. (npx skills add jpwilliams/notes-skill does the same thing if
you would rather not use the GitHub CLI.) Then add the MCP server:
https://notes.jpwilliams.dev/api/v1/mcp
Anything else
Any client that speaks remote MCP can use that URL directly, with no package and nothing installed —
it discovers the rest itself. notes.jpwilliams.dev/install
has the per-client instructions.
What happens next, whichever route you took
A browser opens. Sign in to the account you already have, read what the connection will be able to
do, and give it a name — that name is what appears on every bullet it writes, so make it the thing
you would want to read in the middle of a day's notes. "Work laptop" beats "Claude".
That is the whole setup. No key to issue, no key to paste, no keychain, no claude mcp add and no URL.
You can disconnect it at any time from the 🔑 Machine access page at
notes.jpwilliams.dev, and it stops working immediately.
On the desktop app and the website
The same connection, without the plugin. Add Notes as a custom connector using the URL
https://notes.jpwilliams.dev/api/v1/mcp — the app discovers the rest and sends you to the same screen
to approve it and name it. The plugin is worth having in the terminal because it carries a skill that
teaches Claude when to reach for the notebook; the connector on its own carries the tools and a
shorter version of the same guidance, sent by the server itself.
What it can do
Four tools, and a skill that teaches an agent when to reach for them.
| Tool | What it does |
|---|
list_entities | The shelf: every project, person and topic, most recently mentioned first. |
get_entity | One entity's page — its description, recent mentions with their sub-bullets, what it co-occurs with, its open todos. |
get_day | One day's page as markdown, plus its bullets with ids. |
append_note | Add bullets to a day. |
What it deliberately cannot do
- Append only. It can never edit or delete anything — not your text, not another agent's, not its
own. A correction is a new bullet, which is what a notebook does anyway.
- Existing entities only. A
#tag naming an entity that does not exist rejects the whole call
rather than being silently dropped. Renaming and merging do not exist yet, so a typo would be a
permanent wrong shelf in an index you actually read. You create a project's entity once, by hand.
- No corpus search. Every read is bounded by shape rather than by a cap, which is what makes
reading a project cost the same on a decade of notes as on a month.
What it reads
Your whole notebook — every day, every entity, every todo, including notes lifted out of meeting
transcripts. That is what you are approving on the consent screen, and it says so in those words.
Append and read are all it gets, enforced on the server at the point the data is read rather than as a
line in a tool description that a model may or may not honour.
What you see
Every bullet an agent writes is visible in your day view and marked with the name you gave that
connection. Hover for the credential, the moment it wrote, and whatever the agent said about itself —
its vendor, its model, the conversation it came from. Those last ones are self-reported and labelled as
such; the name and the timestamp are ours, which is the whole reason you name it rather than the
application naming itself.
The mark records origin and never clears. Editing an agent's bullet by hand does not make it
yours — tidying one is the normal case, and a mark that vanished on first touch would be gone from
most of them within a week. Deleting the bullet is the correction gesture.
If you would rather read your day without them, 🔑 Machine access has a switch. Hidden runs leave a
count behind where they were, so a day never quietly pretends nothing was written. The same page lists
every connection and disconnects one instantly — notes it already wrote stay exactly where they are,
still marked with the name you gave it.
Requires
A Notes account. The app is at notes.jpwilliams.dev.
Licence
MIT.