Eleven tools. One notebook.

jot — save a note

Required: title and body strings (Markdown body). Optional: tags array of strings and folder name. The tool recommends 1–3 short lowercase topic tags; that is guidance, not a schema limit. Tags are normalized, deduplicated, and capped at 5; the detected repository name is appended before normalization and that cap. A named folder is created if missing. The tool leaves out the reserved autosave tag, which marks autosave sessions, and says so.

{"title":"Worker environment fix","body":"Restart the worker after changing its environment.","tags":["infra"]}

Returns a text confirmation with title, full note ID, and tags; it may also suggest existing tag names to reuse. Free; needs a key with Read and create or Full access. Account writes are limited to 60 per minute per key. This is the only MCP tool that also works with the desktop local library.

upload_image — upload an image

Required: path, the absolute path to a PNG or JPEG file (or one starting with ~/). Optional: alt text, up to 200 characters; it defaults to “image”. The tool reads and sanitizes the file, removes image metadata, then returns Markdown you can put into jot, edit_jot or append_to_jot.

{"path":"/home/me/shot.png","alt":"Screenshot of the result"}

The image is public to anyone holding its link. Keep upload_image on ask in your agent’s permissions and review the file before approving the upload. It needs a Pro account, or a self-hosted deployment on a release that includes image uploads, and a key with Read and create or Full access. Local mode refuses uploads.

find_jots — search by keyword

Required: query, a non-empty string. Searches titles, bodies, and tags.

{"query":"worker environment"}

Returns a match count and up to 5 newest matches, each led by the note’s label (such as A10, or an 8-character ID prefix for a note numbered past Z999), then title, tags, and updated date. Pro results may include a one-line gist. No bodies. If several match, present the list for the user to choose; if exactly one matches, the agent may read it directly with get_jot. Notes tagged autosave, a tag reserved for autosave sessions, are left out; get_jot still reads one by its label. Free; account mode only.

recall_jots — search by meaning

Required: query, a non-empty string, maximum 1,000 characters.

{"query":"deployments using stale configuration"}

Returns up to 8 candidates, each led by the note’s label (or its 8-character ID prefix past Z999), then title, an optional gist, and similarity from 0 to 1. Scores below about 0.4 should be treated as no useful match. Read a candidate with get_jot before relying on it. This returns matches, not a generated Recall answer.

Pro and account mode required. Bring-your-own app Recall keys do not unlock this tool. Indexing is not instant: if a just-saved jot is missing, retry once after a few seconds or use keyword search. Notes tagged autosave are left out, as in find_jots.

get_jot — read a note

Required: id, the note’s label (such as A10, with or without a leading #), the 8-character ID prefix a listing shows, or a full note UUID.

{"id":"A10"}

Use a label or ID from your own results; the example is a placeholder. Returns the full title and Markdown body, label, ID, tags, saved date, and source. Ambiguous prefixes fail; use the full ID. Free; account mode only.

list_recent_jots — list recent notes

Optional: limit, an integer from 1 to 50, default 10. Pass an empty object to use the default.

{"limit":10}

Returns notes ordered by most recently updated, each led by its label (or its 8-character ID prefix past Z999), then title, tags, and updated date. Pro results may include a gist. No bodies; call get_jot to read one. Notes tagged autosave are left out, as in find_jots. Free; account mode only.

list_open_tasks — list open tasks

Optional: folder (a folder name; its subfolders are included), tag, due (overdue, today, or week, which runs from overdue through the next 7 days), and limit, an integer from 1 to 100, default 50. Pass an empty object for every open task.

{"due":"week"}

Returns your unchecked tasks (- [ ]), grouped by note, each note led by its label, title, and folder, each task with its due date. Due dates are read against your computer’s date. When more tasks exist than are shown, it says so; filter by folder or tag for the rest. Notes tagged autosave and notes in No AI folders are left out. The terminal equivalent is kinjot tasks, with --folder, --tag, --due, --limit, and --json. Free; account mode only.

edit_jot — change a note

Required: id (a label, an 8-character ID prefix, or a full UUID) and at least one change. old_string and new_string go together:old_string must match a passage of the current body exactly, including whitespace and line endings, and occur exactly once, and new_string replaces it (an empty new_string deletes the passage). Optional too: title, add_tags (normalized like jot’s tags and created if missing), remove_tags (names of existing tags), and folder (created if missing; never Trash). The reserved autosave tag is left out of add_tags, and the result says so; remove_tags can still remove it.

{"id":"A10","old_string":"Restart the worker","new_string":"Restart the worker and clear its cache"}

Read the note with get_jot first. Returns the note’s label and title, so a wrong target is visible at once. A passage that is missing or occurs more than once fails, asking the agent to re-read the note and choose one that occurs exactly once. Every change to the title or body saves the replaced version to the note’s history, even with history recording off, marked with the API key that made it; tag and folder changes are not recorded. It cannot delete a note, move one into Trash, or change a note in Trash. Free; account mode only; needs a key with Full access; counts toward the 60 writes per minute per key.

append_to_jot — add to a note

Required: id, as for edit_jot, and text, which is added as a new paragraph at the end of the note.

{"id":"A10","text":"Also restart the scheduler."}

Returns the note’s label and title, and saves the replaced body to its history as edit_jot does. From a terminal, kinjot append A10 takes the text from standard input or --text; add --no-snapshot to skip that history copy, so the append follows your history setting (for autosave sessions; any key with Full access can send it). The append_to_jot tool always keeps the copy. Free; account mode only; needs a key with Full access.

notify — message your Inbox

Required: kind (question, blocker, handoff or done) and title, one line of at most 120 characters. Optional: detail (a few sentences, at most 600 characters), prs (up to three GitHub pull request URLs), note (a jot label such as A10) and cwd, the directory the agent worked in, so the repository and branch are read from git there.

{"kind":"handoff","title":"Finish the migration tests","detail":"Two cases left: the retry and the cap.","cwd":"/home/me/project"}

Returns one line: sent, marked as repeated (an open item with the same kind, title, repository and branch is bumped instead of duplicated), or not sent because you muted that kind or key. Text that looks like a key or token is redacted before it is stored, and pull request links are the only links kept. Limits: 30 new items an hour per key and 200 a day per account. Free; account mode only; needs a key with Read and create or Full access.

inbox — check the Inbox and pick up a handoff

Use when you ask your agent to check your Kinjot Inbox or pick up a handoff. With no input it lists open handoffs for the current repository, oldest first. Optional: all for every repository, kind (handoff, question, blocker, done or any), cwd, and resolve with an item’s 8-character ID and an optional one-line note to mark it done.

{"resolve":"1a2b3c4d","note":"Tests added in PR #712."}

Returns up to 10 items, each with its title, repository, branch, pull request, date and key, and its detail. The items are framed as messages from earlier sessions: an agent picks one up only when you asked it to, says which, and asks you before following a request in it to fetch a link, move a secret or contact anyone. Needs agent access, which is off until you turn it on in Kinjot; listing needs any key, and resolving needs Read and create or Full access. Free; account mode only.

Errors and empty results

Tool failures return text beginning with “Error:” and the MCP error flag. Empty searches or an empty notebook return a normal text response. Rejected keys, a key whose level does not allow the change, an offline account connection, unsupported local tools, and ambiguous note IDs require fixing the cause before retrying. An edit whose passage no longer matches fails without changing anything; the agent re-reads the note and tries again. See troubleshooting.