# Notes · guide for AI agents

Notes is a personal markdown notes app at https://notes.mohitya.dev. The person you work for keeps their to-dos, journals and project notes here and edits them from their phone while you work. Your job is usually to find, read or update those notes.

The notes are a **vault of plain markdown files**. You get the vault as a normal folder (`~/notes` by default) and use your usual tools on it: `ls`, `rg`, `cat`, `sed`, Python, your file editor. The `notes` CLI keeps that folder in sync with the server before and after each command.

## 1. Install the CLI

```bash
curl -fsSL https://notes.mohitya.dev/install.sh | sh
```

This installs a single static binary named `notes` into `~/.local/bin` (or `/usr/local/bin` when writable) and verifies its checksum. Supported: macOS and Linux on x86_64 and arm64. Make sure the install directory is on your `PATH`.

## 2. Sign in

Use the email and password the person gave you. Non-interactive (best for agents):

```bash
export NOTES_SERVER='https://notes.mohitya.dev'
export NOTES_EMAIL='person@example.com'
export NOTES_PASSWORD='their password'
notes sync          # first sync downloads the vault into ~/notes
```

Or interactively: `notes login --email person@example.com`. The session token is saved to `~/.config/notes/config.json`. Set `NOTES_DIR` to put the vault somewhere other than `~/notes`. Never print the password or write it into the notes.

## 3. Work with the notes

Prefix shell commands that touch the vault with `notes --`. It syncs, runs the command, then syncs again and exits with the command's exit code:

```bash
notes -- ls ~/notes
notes -- rg -n -i "dentist" ~/notes
notes -- python3 edit_todos.py
```

When you edit with built-in file tools instead of the shell (read/write/edit tools), run `notes sync` before reading and again after editing. Status lines go to stderr and nothing is printed when nothing changed.

## Rules

- **Re-read before rewriting.** The person may have edited the same note seconds ago on their phone. Edits are merged on the server, but writing back an old copy of a whole file can undo theirs.
- **Prefer small edits** (replace a line, append an item) over rewriting whole files.
- Notes are markdown. The first line is the title. Checklists are `- [ ] item` and `- [x] done`, nested with two spaces per level.
- Folders are directories. A note's filename is its title plus `.md`.
- Images: save the file next to the note (for example `Daily/attachments/chart.png`) and link it with a relative path: `![](attachments/chart.png)`. Only `.md` files and images (png, jpg, gif, webp, heic, svg, avif) sync.
- Deleting a file moves the note to Recently Deleted for 30 days. Deleting more than 10 files in one sync needs `notes sync --yes`; only do that when asked.
- `AGENTS.md` at the vault root holds the person's own instructions for agents. Read it and follow it.
- Run `notes whoami` to check which account and folder you are using.

## Without a shell: MCP

Add `https://notes.mohitya.dev/mcp` as a remote MCP server (streamable HTTP). It signs in with OAuth using the same email and password, and offers `list_notes`, `read_note`, `search_notes` (regex), `edit_note` (exact string replace), `write_note`, `move_note` and `delete_note`. A session token from the HTTP API also works as a Bearer token.

## HTTP API

Base URL https://notes.mohitya.dev. Authenticate with `Authorization: Bearer <token>`. Set a `User-Agent` header; some default library user agents are blocked.

- `POST /api/login` `{"email", "password"}` → `{"token", "email"}`
- `GET /api/changes?since=<seq>` → `{"seq", "notes": [{"id", "path", "kind", "text", "sha", "version", "deleted", "updatedAt", ...}]}`
- `POST /api/push` `{"changes": [{"pushId", "id", "path", "base", "text"}]}`: `base` is the text you started from (null for a new note); the server three-way merges and returns the merged note
- `PUT|GET /api/blobs/<sha256>`: image bytes

The CLI is the easiest client; use the API directly only when you cannot run it.