Keepsake

List contacts in the user's Keepsake CRM. Supports pagination, sorting, field selection (use `fields` to skip long notes when scanning many contacts), filters on linked companies and on last update, and optional last_interaction_date enrichment. Each contact's companies are company records, returned in `companies`.

Get a single contact by ID, including recent entries (interactions), tags, last_interaction_date, and total_entries count.

Create a new contact. first_name is required. last_name is optional (useful for contacts where you only know the first name).

Update an existing contact. Only send the fields you want to change.

Permanently delete a contact and all associated data.

Search contacts by name, email, company, etc. Search is accent-insensitive.

List all companies/organizations in the user's Keepsake CRM. Supports pagination and sorting.

Get a single company by ID, including linked contacts (with roles) and tags.

Create a new company/organization. Only 'name' is required.

Update an existing company. Only send the fields you want to change.

Soft-delete a company. Use permanent=true for hard delete.

Link a contact to a company record (idempotent: linking twice keeps one link). A contact can belong to several companies. Optionally set the contact's role there. Shortcut when you only know the company's name: create_contact / update_contact with `company`.

Remove the link between a contact and a company. Neither the contact nor the company is deleted.

Merge a duplicate company INTO another one: its contacts, entries and tags move to the target (no duplicates), the target's empty details (website, email, phone, address) are filled from it, its notes are appended to the target's, then it is deleted. Use it when two records describe the same organization (e.g. 'CNCP' and 'Cncp'). Confirm with your user which record to keep.

Search companies by name, email, website, or address. Search is accent-insensitive.

List interaction entries (calls, emails, meetings, events, etc.). Supports filtering by type, contact, company, tag (page) and date range.

An ENTRY is a dated interaction log tied to contacts. Records something that happened (call, meeting, email…) on a specific date. Create a new interaction entry. Content supports #tag# and [[tag]] syntax for automatic tag linking.

Update an existing entry. Only send fields you want to change.

Delete an interaction entry.

List tasks. Filter by status (pending/completed), date_type, specific date, company, or tag (page) — e.g. tag_id + status=pending lists a project's open tasks.

Get a single task by ID, with its tags, linked contacts (contact_ids), linked companies (company_ids) and linked notes (note_ids). Use it when you already know which task you need instead of listing everything.

A TASK is an action item to accomplish. Can have due date, recurrence, priority, linked to contacts and tags. Create a new task. Title supports #tag# and [[tag]] for automatic tag linking.

Update an existing task. Only send fields you want to change.

Delete a task.

Mark a task as completed. If the task is recurring, this automatically creates the next occurrence.

Mark a completed task as pending again.

Reschedule a task to a new date.

List notes. QuickNotes (inbox, not yet archived) and Notes (archived, permanent). Filter by pinned or archived status, by tag (page) with `tag_id`, by the day(s) a note is linked to (`date`, or `date_from`/`date_to`) — e.g. "what did I note for tomorrow?" —, or by publication-flow stage with `status` — e.g. "which notes are waiting for review?". Each note carries `dates` (the days it is linked to) and `status` (its stage in the publication flow, or null).

List the stages of the user's publication flow, in order (by default: Idea → In progress → To review → Ready → Published). A note enters this flow when the user may publish it — most notes never do and have no stage. Stages are the user's own: they can rename, recolor, add or remove them, so read this list before setting a stage with update_note or create_note. `category` is fixed: unstarted, started, or published (exactly one stage). Names are in the user's app language.

Takes no parameters.

Get a single note by ID, including its tags, linked contacts, linked tasks, linked notes and the days it is linked to (`dates`). Use this when the user points you at one specific note (e.g. gives you its URL — the UUID is the last path segment) instead of listing everything.

Create a new QuickNote in the Inbox. QuickNotes are temporary captures — use archive_note to transform one into a permanent Note, or pass archived=true to create the permanent Note directly (reference material the user asked you to keep — a project's status note, meeting minutes filed on a page — rather than a capture for them to sort). Content supports #tag# and [[tag]] for automatic tag linking. Pass `dates` to attach the note to one or more days ("note for tomorrow", meeting prep for Thursday): it then surfaces in that day's view while staying in the notes list. A dated note is NOT a task (no action to complete) and NOT the day's intention (see update_day).

Update an existing QuickNote or Note. `dates` REPLACES the full set of days the note is linked to — the way to move a note to another day ("not done, push it to tomorrow"). To add or remove a single day without touching the others, prefer link_note_date / unlink_note_date. `status` moves the note along the publication flow ("this one is ready"); setting a stage on an Inbox QuickNote also keeps it as a Note.

Soft-delete a QuickNote or Note. Use permanent=true for hard delete.

Pin a QuickNote or Note so it stays in view. A pin is a POST-IT: a short reference the user wants always at hand (gate code, hotel room number, Wi-Fi password). Do not pin a note just because it is important — meeting prep is linked to its day, project material to a tag, actions become tasks. Pin only when the user asks or the note is clearly such a post-it.

Unpin a note: it leaves the pinned post-its and stays where it is (Inbox or Notes), nothing else changes. Use when a pinned reference is no longer needed at hand — e.g. a project status note replaced by a newer one, or a project being closed.

Transform a QuickNote into a permanent Note (archive it). Notes appear on contact pages, tag pages, and the Notes section.

Restore a Note back to a QuickNote in the Inbox (unarchive), or restore a deleted note from trash.

List stored days with their intention or question of the day (`note`; `intention` repeats it, null when empty). An intention is valid for its own day only — it does not carry over to the following days. Filter by date range.

Get a specific day by date: its intention or question of the day AND the notes linked to that day (field `notes`, via link_note_date / `dates`). `note` is the intention written for that day (null or '' = none; `intention` repeats it). An intention is valid for its own day only — it does not carry over. Always 200 — `exists: false` means no row is stored for that date; `intention` and the linked notes are returned regardless.

Create or update a day's intention or question of the day (upsert on the date). The `note` field is the intention or question of the day — one short line at the top of the Today view (a mantra, an intention, a single priority, or a question to keep in mind). Not a journal: never write a summary of the day here. An intention is valid for its own day only: it does not carry over to the following days. The user types it by hand each morning, on purpose — do not set it for them unless they ask. `null` or an empty string removes it. NOT for attaching a note to a day: this field is a single line and you would overwrite the user's intention. To put a note on a day, use create_note with `dates` or link_note_date.

List the time blocks of a day's timeline (Day view), in timeline order. A block is either an activity (type 'block') or a task bucket (type 'tasks' — groups the day's untimed tasks). The meta carries the day's raw timeline_order: "b:<uuid>" refs are blocks, bare uuids are tasks inside a bucket's run. Recurring blocks: listing today or a future day first creates that day's recurring blocks if they do not exist yet (same as opening the day in the app), so every block returned has a real id you can update or mark done. A block that repeats carries `repeats: { recurring_block_id, weekdays }` (ISO weekdays, 1 = Monday … 7 = Sunday); otherwise `repeats` is null. Past days are never filled in afterwards. Notes: each block carries `notes` ([{ id, title, content }], real Keepsake notes linked to the block — prepared before, completed after), `note` (the first note's text) and `entry_id` (the short entry that tells the block, created by the app's "Add details" or by create_entry with day_block_id; null if none). A recurring block also carries `kept_notes` (same shape): notes kept by its repetition, shown on every occurrence from the day they were kept (see keep_recurring_block_note) — `notes` and `note` are that day's own notes only.

Create a time block on a day's timeline. The block is auto-placed in the earliest free gap large enough for it (same first-fit engine as the app); pass anchor_time to pin it at a fixed hour instead. Its "b:<id>" ref is inserted into the day's timeline_order for you — never write timeline_order by hand.

Update a time block (title, duration, anchor, note, done). Only send fields you want to change. The block keeps its position in the timeline order. Marking a block done records when it actually happened: it ends now and starts its planned duration earlier (never before the previous done block ended). In the app, a done block then stays at that time in the past of the day, while what is left to do stacks from the current time. A block with a fixed time keeps its hour.

Delete a time block. Its ref is pruned from the day's timeline_order; for a task bucket, the tasks themselves are untouched (they fall back to the day's computed bucket). On a recurring block, this removes it from THAT DAY ONLY (the app's "Remove from today"): the block keeps coming back on the other days, and the skipped day does not break the habit streak. To stop the repetition itself, use stop_recurring_block.

List the user's recurring time blocks: their ideal day / ideal week ("Meditation" every day at 08:00, "Writing" on weekday mornings). A recurring block is also a habit: each day it appears on the timeline as a regular block the user checks off (see list_day_blocks), and consecutive checked days form a streak. `weekdays` is the rule in force on the given date; `next_change` announces a rule already recorded for later (a repetition that starts or stops on a future date). `notes` lists the notes the repetition keeps ([{ note_id, title, from_date, until_date }], until_date excluded, null = no end; see keep_recurring_block_note).

Make a time block come back on chosen weekdays. Two ways: pass `block_id` to turn an EXISTING block into a recurring one (it becomes the first occurrence and keeps its title, duration and fixed time — do this when the block is already on the timeline, otherwise that day would get it twice), or describe a new one (title, duration, optional fixed time) starting on `start_date`. Nothing is created on the timeline right away: each day's block appears when that day is opened in the app or listed with list_day_blocks. With `anchor_time` the block sits at that hour every day; without it, it is placed from the user's wake time and shifts with it.

Change a recurring block FROM A DATE ONWARD (title, duration, fixed time, weekdays). The past is never rewritten: earlier days keep their blocks as they were, and the habit keeps its history. Upcoming occurrences already created and not yet checked are updated, or removed if their day is no longer planned. To change a single day only, use update_day_block on that day's block instead.

Stop a recurring block from a date onward (the app's "Stop repeating"). Past days keep their blocks and the habit keeps its history; upcoming occurrences already created and not yet checked are removed. To skip a single day and keep the repetition, use delete_day_block on that day's block.

List tags (lightweight: the manual tasks_order arrays are omitted — use get_tag for a tag's full ordering). Tags organize contacts, entries, tasks, notes, and companies. Use q to find a tag by name. Archived tags (closed projects) are included unless you pass archived=false; each tag's archived_at tells which.

Get a single tag by ID with all its properties (name, description, color, icon, view mode, favorite status). Includes tasks_order, the manual ordering of the tag page's task list, where entries of the form "h:<header_id>" are section separators (see list_task_headers).

Get items linked to a tag. By default returns every type in full — on large tags that can be a huge response, so prefer types/status/summary to narrow it (e.g. types=['tasks'], status='pending', summary=true to review a project's open tasks). When tasks are included, the response also contains `sections`: the tag page's task sections with their task_ids (header_id null = tasks outside any section).

A TAG is a thematic grouping space. Syntax: #name# or [[name]]. Groups notes, entries, tasks, and contacts. Create a new tag. If a tag with the same name already exists, returns the existing tag.

Update an existing tag. Only send the fields you want to change. Supports name, description, color, icon, favorite status, archiving, and the order of the page's tasks and sections (tasks_order). The description is the place for a page's state (status, deadline, next step): there is no separate field for it.

Permanently delete a tag and all its links to contacts, entries, tasks, notes, and companies. Its #tag# / [[tag]] markers are stripped from all content (the words stay). To fold a duplicate into another tag, use merge_tag instead.

Merge a duplicate tag (page) INTO another one: all its links (contacts, entries, tasks, notes, companies) move to the target without duplicates, every #source# / [[source]] in content is rewritten as the target's name, then the source tag is deleted. Use it when two pages describe the same project or theme (e.g. 'Livre' and 'livre photo'), or when update_tag refuses a rename because the name already exists. Confirm with your user which page to keep.

Link an entity (contact, entry, task, note, or company) to a tag.

Remove the link between an entity and a tag.

List all task headers (section separators used to group tasks on tag pages and day views).

Get a single task header by ID.

Create a new task header (section separator). To show it on a tag page, insert "h:<header_id>" into that tag's tasks_order (get_tag, then update_tag) where the section should start: the tasks listed after it belong to that section.

Update a task header. Only send the fields you want to change.

Permanently delete a task header.

Link an existing contact to a note.

Remove the link between a contact and a note.

Link an existing contact to an entry.

Remove the link between a contact and an entry.

Link an existing contact to a task.

Remove the link between a contact and a task.

Link a company to an entry (the company becomes a participant of that interaction). Idempotent. Companies are separate records from contacts: use this (or company_ids) for an organization, link_entry_contact for a person.

Remove the link between a company and an entry.

Link a company to a task. Idempotent. Companies are separate records from contacts: use this (or company_ids) for an organization, link_task_contact for a person.

Remove the link between a company and a task.

Link a company to a note. Idempotent. Companies are separate records from contacts: use this (or company_ids) for an organization, link_note_contact for a person.

Remove the link between a company and a note.

Link an existing note to a task (non-destructive, N-N). The note stays in the inbox/notes list and the task keeps a live link back to it — use this instead of deleting a note after creating a task from it. The note shows its linked tasks; the task shows the source note.

Remove the link between a note and a task. Both the task and the note survive.

Link an existing note to a time block of the timeline (N-N, non-destructive). A block's notes are where the user prepares it (before) and writes what happened (after) — the same note, completed. The app shows the note's title on the block's card and opens the note right in the block. Get block ids from list_day_blocks.

Remove the link between a note and a time block. Both the block and the note survive.

Keep a note in a recurring block (the app's "Keep for the following days"): from `from_date` on, every occurrence of the repetition shows it — a running log for a project block, a checklist for a routine. Days already planned are included, earlier days are untouched. Nothing is copied: it is one note, the same everywhere. A note written in a recurring block belongs to that day only until it is kept. Get repetition ids from list_recurring_blocks (or `repeats.recurring_block_id` in list_day_blocks); each repetition lists its kept notes in `notes`.

Stop keeping a note in a recurring block (the app's "Stop keeping"): occurrences on or after `from_date` no longer show it, earlier days keep it. The note itself survives. To keep it on one particular day only, link it to that day's block afterwards with link_day_block_note.

Link an existing note to an entry (N-N, non-destructive): the note is the write-up of that interaction, shown as a preview on the entry's card. Typical case: after a meeting block, the short entry ("Meeting · Coffee with Constance") points to the note where the user prepared then wrote the meeting.

Remove the link between a note and an entry. Both the entry and the note survive.

Link two notes together (knowledge base, N-N, non-destructive). The link is symmetric: both notes list each other in their linked-notes section. Use this to connect related ideas — e.g. a note that made you think of another one. Notes can also be linked inline by writing [label](note:uuid) in a note's content.

Remove the manual link between two notes (both notes survive). Links derived from inline [label](note:uuid) markdown in a note's content are preserved — edit the content to remove those.

Link a note to a calendar day. The note then surfaces in that day's view (Today / Day page) while staying in the notes list — the note is the same object, the date is just another way in. Use it for "note for tomorrow", "what to bring Thursday", meeting prep for a given date. Idempotent. A note can be linked to several days. This is NOT the day's intention (update_day) and NOT a task (create_task).

Remove a note from a calendar day (the note survives, untouched). To MOVE a note to another day, prefer update_note with the new `dates` array — one call instead of two. Idempotent.

Get a unified, chronological feed of ALL items related to a contact — entries, tasks, and notes — sorted by date (most recent first). Much more efficient than fetching entries, tasks, and notes separately.

Get all tasks for today: overdue tasks + tasks due today + ASAP tasks. Each task has a 'category' field ('overdue', 'today', or 'asap'). Includes counts per category.

Takes no parameters.

Get only overdue tasks (pending tasks with a due date before today). Sorted by date ascending (oldest first).

Takes no parameters.

Get all items modified since a given timestamp, across all entity types. Perfect for 'heartbeat' checks to see what changed since your last visit. Returns server_time to use as 'since' for the next call.

Search across all Keepsake data — contacts, entries, tasks, notes, and companies. Search is accent-insensitive (e.g., 'berenice' finds 'Bérénice').

List the marginalia attached to a note. A marginalia is working material the user keeps ALONGSIDE a note without it entering the text: an idea, a reference, a link, an excerpt pasted to rewrite a passage later. They are never published, and they are meant to be TEMPORARY — anything worth keeping becomes a note or a linked task. Each one is either attached to a specific passage (`quote` is set) or to the whole note (`quote` is null).

Write in the margin of a note. This is the right move whenever your user asks you to review, critique, proofread or annotate their text: the remark lives alongside the note without ever entering it, and it stays there after the conversation ends — unlike anything you write in the chat. Anchor a remark to a passage by copying that passage VERBATIM into `quote`; the server locates it and stores the surrounding context so the comment survives later edits. Omit `quote` to comment on the note as a whole. A quote that is not found verbatim is refused rather than attached to the wrong place. Your comments render in blue ink in the app, your user's in red — they always know who wrote what. Do not use this to rewrite their text: propose, they decide. And keep comments few and substantive: a note peppered with them is a note the user abandons.

Edit the content of a marginalia. There is no intermediate state: a marginalia exists, or it is deleted. A remark that should outlive the note's revision becomes a note or a linked task instead.

Delete a marginalia. Marginalia are temporary by design, so this is the normal way to retire one — there is no recoverable middle state.

Get best practices and instructions for being an effective Keepsake AI agent. Call this at the start of each session to refresh your instructions.

Takes no parameters.