io.github.seunghan91/ainote

Official52 toolsLive

by seunghan91

Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.

MCP Server: io.github.seunghan91/ainote

The io.github.seunghan91/ainote MCP server provides an agent-native surface for notes, tasks, dev-docs, and vaults. It supports sync and handoffs and exposes both an MCP interface and an OpenAPI dual surface. The package includes 52 tools for interacting with its capabilities.

🛠️ Key Features

Agent-native notes, tasks, dev-docs, and vaults
Sync and handoffs
Dual surface: MCP + OpenAPI
52 tools

🚀 Use Cases

Managing agent-oriented notes and task workflows
Organizing development documentation
Using vault-based storage with synchronization
Passing work between agents via handoffs

⚡ Developer Benefits

MCP integration for tool-based access
OpenAPI compatibility via dual surface
Broad functionality covered by 52 tools

⚠️ Limitations

Limited description available: no details on authentication, data models, or specific tool behaviors beyond the stated categories.

Captured live from the server via tools/list.

list_tasks

List all tasks from AI Note with advanced filtering, date ranges, location search, and sorting

Parameters18

status	string	optional	Filter by task status
is_important	boolean	optional	Filter by important tasks only
limit	number	optional	Maximum number of tasks to return (default: 25, max: 500)
offset	number	optional	Number of tasks to skip for pagination (default: 0). Use with limit to fetch additional pages.
search	string	optional	Search keyword in task content and notes (case-insensitive partial match)
location	string	optional	Filter by location (partial match, e.g., '여의도', '서울')
category_id	string	optional	Filter by category UUID
due_date_start	string	optional	Filter tasks with due_date >= this date (ISO 8601 format)
due_date_end	string	optional	Filter tasks with due_date <= this date (ISO 8601 format)
completed_date_start	string	optional	Filter tasks completed >= this date (ISO 8601 format)
completed_date_end	string	optional	Filter tasks completed <= this date (ISO 8601 format)
created_date_start	string	optional	Filter tasks created >= this date (ISO 8601 format)
created_date_end	string	optional	Filter tasks created <= this date (ISO 8601 format)
overdue	boolean	optional	Filter overdue incomplete tasks (due_date < today)
due_today	boolean	optional	Filter tasks due today
has_notification	boolean	optional	Filter by notification enabled status
sort_by	string	optional	Sort field (default: created_at)
sort_order	string	optional	Sort order (default: desc)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "completed"
      ],
      "description": "Filter by task status"
    },
    "is_important": {
      "type": "boolean",
      "description": "Filter by important tasks only"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of tasks to return (default: 25, max: 500)"
    },
    "offset": {
      "type": "number",
      "description": "Number of tasks to skip for pagination (default: 0). Use with limit to fetch additional pages."
    },
    "search": {
      "type": "string",
      "description": "Search keyword in task content and notes (case-insensitive partial match)"
    },
    "location": {
      "type": "string",
      "description": "Filter by location (partial match, e.g., '여의도', '서울')"
    },
    "category_id": {
      "type": "string",
      "description": "Filter by category UUID"
    },
    "due_date_start": {
      "type": "string",
      "description": "Filter tasks with due_date >= this date (ISO 8601 format)"
    },
    "due_date_end": {
      "type": "string",
      "description": "Filter tasks with due_date <= this date (ISO 8601 format)"
    },
    "completed_date_start": {
      "type": "string",
      "description": "Filter tasks completed >= this date (ISO 8601 format)"
    },
    "completed_date_end": {
      "type": "string",
      "description": "Filter tasks completed <= this date (ISO 8601 format)"
    },
    "created_date_start": {
      "type": "string",
      "description": "Filter tasks created >= this date (ISO 8601 format)"
    },
    "created_date_end": {
      "type": "string",
      "description": "Filter tasks created <= this date (ISO 8601 format)"
    },
    "overdue": {
      "type": "boolean",
      "description": "Filter overdue incomplete tasks (due_date < today)"
    },
    "due_today": {
      "type": "boolean",
      "description": "Filter tasks due today"
    },
    "has_notification": {
      "type": "boolean",
      "description": "Filter by notification enabled status"
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "due_date",
        "created_at",
        "completed_at",
        "updated_at",
        "is_important"
      ],
      "description": "Sort field (default: created_at)"
    },
    "sort_order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Sort order (default: desc)"
    }
  }
}

create_task

Create a new task in AI Note. Supports full task creation with dates, times, location, notes, and notifications.

Parameters16

content	string	required	Task content (required)
is_important	boolean	optional	Mark task as important (default: false)
due_date	string	optional	Due date in ISO format (e.g., '2026-01-28' or '2026-01-28T15:00:00+09:00')
due_time	string	optional	Due time in HH:MM format (e.g., '15:00'). If not provided, task is treated as all-day.
start_date	string	optional	Start date for date range tasks in ISO format (e.g., for multi-day events)
is_all_day	boolean	optional	Mark as all-day event — suppresses time-of-day rendering.
category_id	string	optional	Category ID (UUID) to organize the task
notes	string	optional	Additional notes or details for the task
location	string	optional	Location where the task takes place
location_lat	number	optional	GPS latitude. Pair with location_lng.
location_lng	number	optional	GPS longitude. Pair with location_lat.
travel_time	number	optional	Minutes of travel time to allow before due_date.
has_notification	boolean	optional	Enable reminder notifications (default: false)
reminder_timing	integer	optional	Minutes before due time to send reminder (e.g., 10 for 10 minutes before). Default: 30. Only used when has_notification is true.
reminder_timings	array	optional	Multiple reminder offsets in minutes before due time (e.g., [10, 60] fires 10 min and 1 hour before). Overrides reminder_timing if provided.
repeat_rule	string	optional	Recurrence rule (e.g., 'daily', 'weekly', 'monthly', 'yearly', or RRULE format)

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Task content (required)"
    },
    "is_important": {
      "type": "boolean",
      "description": "Mark task as important (default: false)"
    },
    "due_date": {
      "type": "string",
      "description": "Due date in ISO format (e.g., '2026-01-28' or '2026-01-28T15:00:00+09:00')"
    },
    "due_time": {
      "type": "string",
      "description": "Due time in HH:MM format (e.g., '15:00'). If not provided, task is treated as all-day."
    },
    "start_date": {
      "type": "string",
      "description": "Start date for date range tasks in ISO format (e.g., for multi-day events)"
    },
    "is_all_day": {
      "type": "boolean",
      "description": "Mark as all-day event — suppresses time-of-day rendering."
    },
    "category_id": {
      "type": "string",
      "description": "Category ID (UUID) to organize the task"
    },
    "notes": {
      "type": "string",
      "description": "Additional notes or details for the task"
    },
    "location": {
      "type": "string",
      "description": "Location where the task takes place"
    },
    "location_lat": {
      "type": "number",
      "description": "GPS latitude. Pair with location_lng."
    },
    "location_lng": {
      "type": "number",
      "description": "GPS longitude. Pair with location_lat."
    },
    "travel_time": {
      "type": "number",
      "description": "Minutes of travel time to allow before due_date."
    },
    "has_notification": {
      "type": "boolean",
      "description": "Enable reminder notifications (default: false)"
    },
    "reminder_timing": {
      "type": "integer",
      "description": "Minutes before due time to send reminder (e.g., 10 for 10 minutes before). Default: 30. Only used when has_notification is true."
    },
    "reminder_timings": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Multiple reminder offsets in minutes before due time (e.g., [10, 60] fires 10 min and 1 hour before). Overrides reminder_timing if provided."
    },
    "repeat_rule": {
      "type": "string",
      "description": "Recurrence rule (e.g., 'daily', 'weekly', 'monthly', 'yearly', or RRULE format)"
    }
  },
  "required": [
    "content"
  ]
}

update_task

Update an existing task. All fields are optional except id.

Parameters18

id	string	required	Task ID (required)
content	string	optional	New task content
is_important	boolean	optional	Update important status
completed_at	string	optional	Mark as completed (ISO format) or 'null' to uncomplete
due_date	string	optional	Update due date in ISO format (or 'null' to clear)
due_time	string	optional	Update due time in HH:MM format (or 'null' to make all-day)
start_date	string	optional	Update start date in ISO format (or 'null' to clear)
is_all_day	boolean	optional	Toggle all-day mode.
category_id	string	optional	Update category ID (or 'null' to remove category)
notes	string	optional	Update notes (or 'null' to clear)
location	string	optional	Update location (or 'null' to clear)
location_lat	number	optional	Update GPS latitude.
location_lng	number	optional	Update GPS longitude.
travel_time	number	optional	Update travel-time minutes.
has_notification	boolean	optional	Enable/disable reminder notifications
reminder_timing	integer	optional	Minutes before due time to send reminder (e.g., 10 for 10 minutes before). Only used when has_notification is true.
reminder_timings	array	optional	Multiple reminder offsets in minutes before due time (e.g., [10, 60]). Pass empty array [] to clear.
repeat_rule	string	optional	Update recurrence rule (or 'null' to make non-recurring)

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Task ID (required)"
    },
    "content": {
      "type": "string",
      "description": "New task content"
    },
    "is_important": {
      "type": "boolean",
      "description": "Update important status"
    },
    "completed_at": {
      "type": "string",
      "description": "Mark as completed (ISO format) or 'null' to uncomplete"
    },
    "due_date": {
      "type": "string",
      "description": "Update due date in ISO format (or 'null' to clear)"
    },
    "due_time": {
      "type": "string",
      "description": "Update due time in HH:MM format (or 'null' to make all-day)"
    },
    "start_date": {
      "type": "string",
      "description": "Update start date in ISO format (or 'null' to clear)"
    },
    "is_all_day": {
      "type": "boolean",
      "description": "Toggle all-day mode."
    },
    "category_id": {
      "type": "string",
      "description": "Update category ID (or 'null' to remove category)"
    },
    "notes": {
      "type": "string",
      "description": "Update notes (or 'null' to clear)"
    },
    "location": {
      "type": "string",
      "description": "Update location (or 'null' to clear)"
    },
    "location_lat": {
      "type": "number",
      "description": "Update GPS latitude."
    },
    "location_lng": {
      "type": "number",
      "description": "Update GPS longitude."
    },
    "travel_time": {
      "type": "number",
      "description": "Update travel-time minutes."
    },
    "has_notification": {
      "type": "boolean",
      "description": "Enable/disable reminder notifications"
    },
    "reminder_timing": {
      "type": "integer",
      "description": "Minutes before due time to send reminder (e.g., 10 for 10 minutes before). Only used when has_notification is true."
    },
    "reminder_timings": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Multiple reminder offsets in minutes before due time (e.g., [10, 60]). Pass empty array [] to clear."
    },
    "repeat_rule": {
      "type": "string",
      "description": "Update recurrence rule (or 'null' to make non-recurring)"
    }
  },
  "required": [
    "id"
  ]
}

delete_task

Soft-delete a task by ID. Destructive but reversible within 30 days (TaskCleanupJob purges trash daily at 2am KST). Returns 404 if the task does not exist or is not owned by the authenticated user.

Parameters1

string

required

Task ID to delete

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Task ID to delete"
    }
  },
  "required": [
    "id"
  ]
}

list_categories

List all task categories for the authenticated user. Returns id/name/color/icon/task_count tuples. Read-only — use create_task with category_id to assign tasks to a category.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

list_papers

List notes/papers from AI Note. Supports keyword search across title and content, category filtering, pagination, and sorting. Returns id/title/content_preview/category_id/created_at. Use this when the user asks 'find my note about X', 'what did I write on Y', or wants to search their knowledge base.

Parameters8

search	string	optional	Keyword to match in paper title or content (case-insensitive partial match)
category_id	string	optional	Filter by category UUID
paper_category_id	string	optional	Filter by paper-specific folder UUID
source_type	string	optional	Filter by source type (e.g., 'manual', 'youtube', 'url', 'clipboard')
limit	number	optional	Maximum number of papers to return (default: 25, max: 200)
offset	number	optional	Number to skip for pagination (default: 0)
sort_by	string	optional	Sort field (default: updated_at)
sort_order	string	optional	Sort order (default: desc)

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Keyword to match in paper title or content (case-insensitive partial match)"
    },
    "category_id": {
      "type": "string",
      "description": "Filter by category UUID"
    },
    "paper_category_id": {
      "type": "string",
      "description": "Filter by paper-specific folder UUID"
    },
    "source_type": {
      "type": "string",
      "description": "Filter by source type (e.g., 'manual', 'youtube', 'url', 'clipboard')"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of papers to return (default: 25, max: 200)"
    },
    "offset": {
      "type": "number",
      "description": "Number to skip for pagination (default: 0)"
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "created_at",
        "updated_at",
        "title"
      ],
      "description": "Sort field (default: updated_at)"
    },
    "sort_order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Sort order (default: desc)"
    }
  }
}

list_dev_docs

List dev documents under the dev/ category hierarchy. Filter by subcategory (claude, cursor, windsurf, copilot, docs, etc.), search by title, or filter by content type.

Parameters3

category	string	optional	Subcategory filter (claude, cursor, windsurf, copilot, docs, etc.). Omit to list all dev docs.
search	string	optional	Search keyword in document title
content_type	string	optional	Filter by content type

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "Subcategory filter (claude, cursor, windsurf, copilot, docs, etc.). Omit to list all dev docs."
    },
    "search": {
      "type": "string",
      "description": "Search keyword in document title"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "markdown",
        "json",
        "yaml",
        "text"
      ],
      "description": "Filter by content type"
    }
  }
}

get_dev_doc

Get a single dev document by title or id. Returns full content.

Parameters4

title	string	optional	Document title (e.g., project-a-memory.md)
id	string	optional	Document UUID
category	string	optional	Subcategory (claude, cursor, etc.) to disambiguate title
include_versions	boolean	optional	Include version history (default: false)

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Document title (e.g., project-a-memory.md)"
    },
    "id": {
      "type": "string",
      "description": "Document UUID"
    },
    "category": {
      "type": "string",
      "description": "Subcategory (claude, cursor, etc.) to disambiguate title"
    },
    "include_versions": {
      "type": "boolean",
      "description": "Include version history (default: false)"
    }
  }
}

create_dev_doc

Save a document to AI Note cloud for multi-device sync and persistent storage. PRIMARY USE CASES: - Memory files: ~/.claude/projects/.../memory/MEMORY.md (AI context that survives device switches) - AI config files: CLAUDE.md, .cursorrules, .windsurfrules (not in git, local-only) - Local env notes: API keys reference, server credentials (NOT actual secret values) - Project notes: architecture decisions, dev diaries, planning docs MULTI-DEVICE WORKFLOW: Laptop → push: create_dev_doc(title, content, local_path="~/.claude/.../MEMORY.md") Desktop → pull: pull_dev_docs() → automatically writes files to their local paths CATEGORIES (subcategories under dev/): - memory: Claude/AI memory files (~/.claude/projects/.../memory/) - claude: CLAUDE.md files and Claude-specific configs - cursor: .cursorrules files - env: environment notes and config references - docs: general project documentation Set local_path to enable pull_dev_docs auto-sync to this machine.

Parameters6

title	string	required	Filename as title (e.g., ainote-memory.md, project-claude.md)
content	string	required	Full file content (markdown, json, yaml, text)
category	string	optional	Subcategory: memory \| claude \| cursor \| env \| docs \| custom. Default: docs
content_type	string	optional	Content type. Auto-detected from title extension if omitted.
local_path	string	optional	Absolute path on this machine (e.g., ~/.claude/projects/-Users-seunghan/memory/MEMORY.md). Used by pull_dev_docs to restore file on other devices. Supports ~ expansion.
memory_type	string	optional	Memory update semantics: 'state' = latest value replaces the past (used by memory_search latest_state mode), 'event' = immutable accumulating log, 'preference' = user preference. Omit for plain documents.

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Filename as title (e.g., ainote-memory.md, project-claude.md)"
    },
    "content": {
      "type": "string",
      "description": "Full file content (markdown, json, yaml, text)"
    },
    "category": {
      "type": "string",
      "description": "Subcategory: memory | claude | cursor | env | docs | custom. Default: docs"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "markdown",
        "json",
        "yaml",
        "text"
      ],
      "description": "Content type. Auto-detected from title extension if omitted."
    },
    "local_path": {
      "type": "string",
      "description": "Absolute path on this machine (e.g., ~/.claude/projects/-Users-seunghan/memory/MEMORY.md). Used by pull_dev_docs to restore file on other devices. Supports ~ expansion."
    },
    "memory_type": {
      "type": "string",
      "enum": [
        "state",
        "event",
        "preference"
      ],
      "description": "Memory update semantics: 'state' = latest value replaces the past (used by memory_search latest_state mode), 'event' = immutable accumulating log, 'preference' = user preference. Omit for plain documents."
    }
  },
  "required": [
    "title",
    "content"
  ]
}

update_dev_doc

Update an existing dev document. Supports replace (default), append, or prepend modes. Optionally update the local_path for sync.

Parameters7

title	string	optional	Document title
id	string	optional	Document UUID
category	string	optional	Subcategory to disambiguate title
content	string	required	New content
mode	string	optional	Update mode (default: replace)
local_path	string	optional	Update the local file path for multi-device sync
memory_type	string	optional	Set the memory update semantics (state \| event \| preference). Pass null/empty to clear.

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Document title"
    },
    "id": {
      "type": "string",
      "description": "Document UUID"
    },
    "category": {
      "type": "string",
      "description": "Subcategory to disambiguate title"
    },
    "content": {
      "type": "string",
      "description": "New content"
    },
    "mode": {
      "type": "string",
      "enum": [
        "replace",
        "append",
        "prepend"
      ],
      "description": "Update mode (default: replace)"
    },
    "local_path": {
      "type": "string",
      "description": "Update the local file path for multi-device sync"
    },
    "memory_type": {
      "type": "string",
      "enum": [
        "state",
        "event",
        "preference"
      ],
      "description": "Set the memory update semantics (state | event | preference). Pass null/empty to clear."
    }
  },
  "required": [
    "content"
  ]
}

pull_dev_docs

Restore all synced files to this device. Fetches every dev doc that has a local_path set and writes the content to that path on disk. WHEN TO USE: - First time setup on a new machine (desktop, laptop, etc.) - After reinstalling macOS or setting up a fresh environment - To restore Claude memory files, CLAUDE.md configs, and other local-only files WHAT IT DOES: 1. Fetches all your dev docs that have local_path set 2. Creates any missing parent directories automatically 3. Writes the file content to each local_path on THIS machine 4. Reports success/failure for each file TYPICAL FILES RESTORED: - ~/.claude/projects/.../memory/MEMORY.md (AI context memory) - ~/projects/*/CLAUDE.md (project-specific AI instructions) - .cursorrules, .windsurfrules (editor AI configs) Run this once after setting up ainote MCP on a new device.

Parameters1

delete_dev_doc

Soft-delete a dev document by title or UUID. Reversible from trash. Pass `category` when multiple docs share the same title across subcategories (memory/claude/cursor/env/docs).

Parameters3

title	string	optional	Document title
id	string	optional	Document UUID
category	string	optional	Subcategory to disambiguate title

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Document title"
    },
    "id": {
      "type": "string",
      "description": "Document UUID"
    },
    "category": {
      "type": "string",
      "description": "Subcategory to disambiguate title"
    }
  }
}

list_dev_categories

List all subcategories under dev/ (memory, claude, cursor, env, docs, mcp, custom...) with document counts. Use to discover which categories exist before calling list_dev_docs with a category filter.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

signup_and_get_key

Create a new AI Note account and get an MCP API key. No authentication required. Use this if you don't have an account yet.

Parameters3

email	string	required	Email address for the new account
password	string	required	Password (minimum 6 characters)
name	string	optional	Display name (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Email address for the new account"
    },
    "password": {
      "type": "string",
      "description": "Password (minimum 6 characters)"
    },
    "name": {
      "type": "string",
      "description": "Display name (optional)"
    }
  },
  "required": [
    "email",
    "password"
  ]
}

login_and_get_key

Log in to an existing AI Note account and return an MCP API key. No prior authentication required. SIDE EFFECT: if the user has no MCP key yet, this call creates one (write to user.mcp_keys), so it is NOT idempotent and must be gated like other key-creation flows.

Parameters2

email	string	required	Your account email address
password	string	required	Your account password

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Your account email address"
    },
    "password": {
      "type": "string",
      "description": "Your account password"
    }
  },
  "required": [
    "email",
    "password"
  ]
}

get_setup_guide

Get instructions for setting up AI Note MCP in Claude Desktop, Cursor, or other MCP clients. No authentication required.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

vault_list

List the authenticated user's GitHub-backed vaults. Each entry includes slug, github_repo_full_name, sync status, indexed file count, and is_primary flag. Read-only. Pair with vault_clone to get the git clone URL or vault_sync to read/write vault files.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

vault_create

Create a new private vault as a GitHub repository under the user's account. Requires the user to have completed the GitHub App install flow first.

Parameters2

name	string	required	Vault name. Slug is derived from this value and used as the GitHub repo name.
description	string	optional	Optional GitHub repo description.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Vault name. Slug is derived from this value and used as the GitHub repo name."
    },
    "description": {
      "type": "string",
      "description": "Optional GitHub repo description."
    }
  },
  "required": [
    "name"
  ]
}

vault_clone

Return the GitHub HTTPS clone URL for an existing vault. Authentication is via the user's normal GitHub credentials (PAT or gh CLI).

Parameters2

name	string	required	Vault name or slug.
target_path	string	optional	Preferred local clone path for the returned instructions.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Vault name or slug."
    },
    "target_path": {
      "type": "string",
      "description": "Preferred local clone path for the returned instructions."
    }
  },
  "required": [
    "name"
  ]
}

vault_connect_status

Check whether the user has installed the ainote GitHub App. If connected, returns account_login + installation_id. If not, returns an install_url to surface to the user. Read-only; talks to GitHub API.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

vault_sync

Wrapper around vault file sync. action=list|pull|push to work against the primary vault. For push: WAF-bypass via `content_b64` or `content: '__B64__:...'` prefix (mirrors sync_push).

Parameters5

action	string	optional	Sync action. Default list.
path	string	optional	Relative path filter or target file path.
content	string	optional	Required for push (or `content_b64`). Prefix with '__B64__:' for WAF bypass.
content_b64	string	optional	Optional: base64-encoded content (use INSTEAD of `content`) for WAF-bypass on large bodies. Server decodes before storing.
since	string	optional	ISO 8601 timestamp for incremental pull.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "pull",
        "push"
      ],
      "description": "Sync action. Default list."
    },
    "path": {
      "type": "string",
      "description": "Relative path filter or target file path."
    },
    "content": {
      "type": "string",
      "description": "Required for push (or `content_b64`). Prefix with '__B64__:' for WAF bypass."
    },
    "content_b64": {
      "type": "string",
      "description": "Optional: base64-encoded content (use INSTEAD of `content`) for WAF-bypass on large bodies. Server decodes before storing."
    },
    "since": {
      "type": "string",
      "description": "ISO 8601 timestamp for incremental pull."
    }
  }
}

sync_push

Push a markdown file into the primary vault. Optional CAS via base_sha to detect concurrent multi-PC writes (Layer 3 of multi-PC sync plan). WAF-bypass tip: large bodies (~10KB+) that get false-positive blocked at Cloudflare can be sent via `content_b64` (base64-encoded) OR `content` prefixed with `__B64__:` instead.

Parameters8

path	string	required	Relative file path (e.g., 'global/MEMORY.md', 'launchcrew/firebase.md'). No leading slash, no '..'.
content	string	optional	Full file content (markdown text). Alternatively prefix with '__B64__:' followed by base64 payload for WAF bypass.
content_b64	string	optional	Optional: base64-encoded file content (use INSTEAD of `content`). For WAF-bypass on large bodies. Server decodes before storing. If both supplied, content_b64 wins.
base_sha	string	optional	Optional: git_sha the client last observed for this path. When present, server compares with current git_sha and returns -32009 conflict on mismatch (with current content for 3-way diff). Omit for legacy LWW behavior (response will include a `warning` field nudging clients to upgrade).
device_id	string	optional	Optional: client device identifier (e.g., from ~/.claude/ainote-sync/device.id). Stored on FileIndex so future conflict responses can report which device last wrote the path.
force	boolean	optional	Optional: when true, skip CAS check even if base_sha is supplied. Use only for intentional overwrites; presence is auditable via warning logs.
resolves_conflict_id	string	optional	Optional: UUID of a vault_conflicts row this push resolves. When supplied, server validates ownership/unresolved/path/sha and atomically marks the conflict as resolution=clean inside the same transaction as the file_indices write. Validation failure rolls back the whole push and returns -32009 stale_conflict_id.
supports_superseded	boolean	optional	Optional capability opt-in. When true AND resolves_conflict_id points at an already-resolved conflict whose (path, remote_sha) matches this push, the server returns a NORMAL 200 with resource_data {status:'superseded', reason:'resolved_elsewhere', applied:false, git_sha:<current remote>} instead of a -32009 error, so the client pulls to converge. Omit (default) to keep the legacy -32009 contract.

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Relative file path (e.g., 'global/MEMORY.md', 'launchcrew/firebase.md'). No leading slash, no '..'."
    },
    "content": {
      "type": "string",
      "description": "Full file content (markdown text). Alternatively prefix with '__B64__:' followed by base64 payload for WAF bypass."
    },
    "content_b64": {
      "type": "string",
      "description": "Optional: base64-encoded file content (use INSTEAD of `content`). For WAF-bypass on large bodies. Server decodes before storing. If both supplied, content_b64 wins."
    },
    "base_sha": {
      "type": "string",
      "description": "Optional: git_sha the client last observed for this path. When present, server compares with current git_sha and returns -32009 conflict on mismatch (with current content for 3-way diff). Omit for legacy LWW behavior (response will include a `warning` field nudging clients to upgrade)."
    },
    "device_id": {
      "type": "string",
      "description": "Optional: client device identifier (e.g., from ~/.claude/ainote-sync/device.id). Stored on FileIndex so future conflict responses can report which device last wrote the path."
    },
    "force": {
      "type": "boolean",
      "description": "Optional: when true, skip CAS check even if base_sha is supplied. Use only for intentional overwrites; presence is auditable via warning logs."
    },
    "resolves_conflict_id": {
      "type": "string",
      "description": "Optional: UUID of a vault_conflicts row this push resolves. When supplied, server validates ownership/unresolved/path/sha and atomically marks the conflict as resolution=clean inside the same transaction as the file_indices write. Validation failure rolls back the whole push and returns -32009 stale_conflict_id."
    },
    "supports_superseded": {
      "type": "boolean",
      "description": "Optional capability opt-in. When true AND resolves_conflict_id points at an already-resolved conflict whose (path, remote_sha) matches this push, the server returns a NORMAL 200 with resource_data {status:'superseded', reason:'resolved_elsewhere', applied:false, git_sha:<current remote>} instead of a -32009 error, so the client pulls to converge. Omit (default) to keep the legacy -32009 contract."
    }
  },
  "required": [
    "path"
  ]
}

sync_push_batch

Push MANY files into the primary vault in ONE call. Use this instead of looping sync_push whenever you have more than a couple of changed paths — the cost of sync_push is round trips, not bytes. Per-item semantics are identical to sync_push (Layer 3 base_sha CAS, superseded contract, content_b64 WAF fallback). Partial success is normal and returns HTTP 200: read `results[]` and match entries by `path`, NOT by position. A conflict result always carries `remote_sha` + `conflict_reason` so you can go straight to sync_merge. Request-level failures (duplicate paths in one batch, idempotency key reused with a different payload, >200 items, >4MB) return 4xx and apply NOTHING. Each item MUST carry `content_sha` (SHA1 hex of the decoded body, same algorithm as git_sha) — it powers both the integrity check and the retry-safe `skipped_identical` result.

Parameters4

items	array	required	Up to 200 push items, 4MB total, one entry per unique path. Duplicate paths reject the whole batch.
idempotency_key	string	required	REQUIRED. Opaque client-generated UUID, one per batch ATTEMPT-SET: reuse the same key when retrying the same items after a timeout (the server replays the stored results instead of re-applying), and generate a NEW key whenever the items change. Reusing a key with a different payload is a 400 collision, never a silent replay. Do not derive it from paths or content.
device_id	string	optional	Optional batch-level device identifier; per-item device_id overrides it.
supports_superseded	boolean	optional	Same capability opt-in as sync_push, applied to every item in the batch.

Raw schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "Up to 200 push items, 4MB total, one entry per unique path. Duplicate paths reject the whole batch.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Relative file path. No leading slash, no '..'."
          },
          "content": {
            "type": "string",
            "description": "Full file content. May use the '__B64__:' prefix like sync_push."
          },
          "content_b64": {
            "type": "string",
            "description": "Optional base64 body (use INSTEAD of content) for WAF bypass. Wins over content if both are present."
          },
          "content_sha": {
            "type": "string",
            "description": "REQUIRED. SHA1 hex of the decoded content. Mismatch fails this item only (status 'error'); equality with the current remote git_sha yields 'skipped_identical' instead of a conflict, which is what makes a crashed batch safe to retry."
          },
          "base_sha": {
            "type": "string",
            "description": "Same tri-state semantics as sync_push: omit for legacy LWW, null to assert the path does not exist yet, or the last observed git_sha for CAS."
          },
          "resolves_conflict_id": {
            "type": "string",
            "description": "Optional vault_conflicts UUID this item closes. Requires a non-null base_sha and force=false."
          },
          "force": {
            "type": "boolean",
            "description": "Optional per-item CAS bypass (audited). Suppresses the skipped_identical short-circuit."
          },
          "device_id": {
            "type": "string",
            "description": "Optional per-item device id; falls back to the batch-level device_id."
          }
        },
        "required": [
          "path",
          "content_sha"
        ]
      }
    },
    "idempotency_key": {
      "type": "string",
      "description": "REQUIRED. Opaque client-generated UUID, one per batch ATTEMPT-SET: reuse the same key when retrying the same items after a timeout (the server replays the stored results instead of re-applying), and generate a NEW key whenever the items change. Reusing a key with a different payload is a 400 collision, never a silent replay. Do not derive it from paths or content."
    },
    "device_id": {
      "type": "string",
      "description": "Optional batch-level device identifier; per-item device_id overrides it."
    },
    "supports_superseded": {
      "type": "boolean",
      "description": "Same capability opt-in as sync_push, applied to every item in the batch."
    }
  },
  "required": [
    "items",
    "idempotency_key"
  ]
}

sync_pull

Legacy alias for pulling files from the primary vault.

Parameters2

since	string	optional	ISO 8601 timestamp. Only return files updated after this time. Omit to get all files.
path	string	optional	Optional directory filter (e.g., 'global' to pull only global files)

Raw schema

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "description": "ISO 8601 timestamp. Only return files updated after this time. Omit to get all files."
    },
    "path": {
      "type": "string",
      "description": "Optional directory filter (e.g., 'global' to pull only global files)"
    }
  }
}

sync_list

Legacy alias for listing files in the primary vault.

Parameters1

path

string

optional

Directory to list (e.g., 'global'). Omit to list all files.

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Directory to list (e.g., 'global'). Omit to list all files."
    }
  }
}

sync_delete

Delete a file from the primary vault. Optional CAS via base_sha to detect concurrent multi-PC writes. Protected paths (global/memory/, global/skills/, global/planning/, global/claude-config/, handoffs/) require base_sha or explicit force:true (audited). Idempotent: deleting a non-existent path returns success with deleted:false.

Parameters4

path	string	required	Relative file path to delete (e.g., 'global/_waf_probe.md'). No leading slash, no '..'.
base_sha	string	optional	Optional: git_sha the client last observed for this path. When present, server compares with current git_sha and returns -32009 conflict on mismatch (with current content for 3-way diff).
device_id	string	optional	Optional: client device identifier for audit log (e.g., from ~/.claude/ainote-sync/device.id).
force	boolean	optional	Optional: when true, skip CAS check even if base_sha is supplied. Use only for intentional overwrites; presence is auditable via warning logs.

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Relative file path to delete (e.g., 'global/_waf_probe.md'). No leading slash, no '..'."
    },
    "base_sha": {
      "type": "string",
      "description": "Optional: git_sha the client last observed for this path. When present, server compares with current git_sha and returns -32009 conflict on mismatch (with current content for 3-way diff)."
    },
    "device_id": {
      "type": "string",
      "description": "Optional: client device identifier for audit log (e.g., from ~/.claude/ainote-sync/device.id)."
    },
    "force": {
      "type": "boolean",
      "description": "Optional: when true, skip CAS check even if base_sha is supplied. Use only for intentional overwrites; presence is auditable via warning logs."
    }
  },
  "required": [
    "path"
  ]
}

sync_merge

Compute a stateless 3-way merge for a vault file. Server runs `git merge-file --diff3 --stdout` over (base_text, local_text, current remote from file_indices) and returns the merged text plus the exact remote_sha it merged against. NO database mutation — to commit the result, follow up with sync_push(content=merged_text, base_sha=merged_against.remote_sha, resolves_conflict_id=conflict_id).

Parameters5

path	string	required	Relative vault path (e.g., 'global/MEMORY.md').
base_text	string	required	Common ancestor text — what the client had cached when it started editing. Source: client state.json baseline. Required.
base_sha	string	optional	Optional: git_sha the client believes is the merge base. When supplied, server verifies (informational; merge still runs).
local_text	string	required	Current local text on the client (post-edit). Required.
device_id	string	optional	Optional: client device identifier. Recorded on any vault_conflict row created downstream.

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Relative vault path (e.g., 'global/MEMORY.md')."
    },
    "base_text": {
      "type": "string",
      "description": "Common ancestor text — what the client had cached when it started editing. Source: client state.json baseline. Required."
    },
    "base_sha": {
      "type": "string",
      "description": "Optional: git_sha the client believes is the merge base. When supplied, server verifies (informational; merge still runs)."
    },
    "local_text": {
      "type": "string",
      "description": "Current local text on the client (post-edit). Required."
    },
    "device_id": {
      "type": "string",
      "description": "Optional: client device identifier. Recorded on any vault_conflict row created downstream."
    }
  },
  "required": [
    "path",
    "base_text",
    "local_text"
  ]
}

sync_diff

Return the unified diff (and raw remote text) of a vault file. Useful for surfacing what `sync_merge` would conflict on, or for the client to render a `git diff` view before pushing. NO database mutation. Server has no history — base_text must be supplied by the caller if a 3-way view is needed; otherwise this returns remote_text only.

Parameters3

path	string	required	Relative vault path.
local_text	string	optional	Optional: client's current text. When supplied, response includes unified diff (remote → local).
base_text	string	optional	Optional: client's baseline (last-known remote). When supplied along with local_text, response includes both diffs (base → remote, base → local) so the client can render a 3-way view.

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Relative vault path."
    },
    "local_text": {
      "type": "string",
      "description": "Optional: client's current text. When supplied, response includes unified diff (remote → local)."
    },
    "base_text": {
      "type": "string",
      "description": "Optional: client's baseline (last-known remote). When supplied along with local_text, response includes both diffs (base → remote, base → local) so the client can render a 3-way view."
    }
  },
  "required": [
    "path"
  ]
}

sync_pending_conflicts

List unresolved vault_conflicts rows for the authenticated user's primary vault. Used by clients (e.g. SessionStart hook) to surface conflicts that need merge attention. Returns up to `limit` rows ordered by most recent first.

Parameters2

limit	integer	optional	Optional: max rows to return (default 50, max 200).
path	string	optional	Optional: filter to a specific path.

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Optional: max rows to return (default 50, max 200)."
    },
    "path": {
      "type": "string",
      "description": "Optional: filter to a specific path."
    }
  }
}

sync_audit_layer5

Record the result of a client-side Layer 5 codex review (sync.py merge gate) as a vault_events row. Body of the review is NOT stored — only an HMAC digest of the summary so operators can correlate without exposing review content. Opt-in: server skips writes (still returns success) unless ENV['AINOTE_LAYER5_AUDIT']='on' AND a versioned HMAC secret is configured. Used by the sync.py SessionStart hook + merge command to surface 'why was this blocked?' across multi-PC sessions.

Parameters5

path	string	required	Vault path the review covered.
verdict	string	required	One of: pass, flag, block, error.
summary	string	optional	Free-form codex output summary. Server HMACs this; raw text is NEVER stored.
chunk_count	integer	optional	Optional: number of diff chunks the client fed to codex.
duration_ms	integer	optional	Optional: wall-clock time of the codex review on the client.

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Vault path the review covered."
    },
    "verdict": {
      "type": "string",
      "description": "One of: pass, flag, block, error."
    },
    "summary": {
      "type": "string",
      "description": "Free-form codex output summary. Server HMACs this; raw text is NEVER stored."
    },
    "chunk_count": {
      "type": "integer",
      "description": "Optional: number of diff chunks the client fed to codex."
    },
    "duration_ms": {
      "type": "integer",
      "description": "Optional: wall-clock time of the codex review on the client."
    }
  },
  "required": [
    "path",
    "verdict"
  ]
}

handoff_save

Save a session handoff note for cross-device / cross-session continuation. Stored at handoffs/{project}-{topic}-{YYYY-MM-DD}.txt in the user's primary vault. Use the optional `time` param (HHMM, KST) to disambiguate multiple handoffs saved on the same day — it is appended to the topic slug (e.g. topic='phase-d', time='1555' → handoffs/{project}-phase-d-1555-{date}.txt).

Parameters6

project	string	required	Project slug, e.g. 'logi', 'ainote', 'krx_ai'. Lowercase, no spaces.
topic	string	required	Short topic slug for this handoff, e.g. 'phase-d-port', 'oauth-fix'. Lowercase-hyphen.
content	string	required	Full handoff text. Should follow the session-handoff skill template (현재 상태 / 작업 위치 / 수정 파일 / 결정 사항 / 다음 STEP / 알려진 이슈). WAF-bypass tip: prefix the string with '__B64__:' followed by base64-encoded payload to bypass Render/Cloudflare edge WAF for large bodies (~10KB+) that get false-positive blocked as SQLi/cmd-injection.
content_b64	string	optional	Optional: base64-encoded handoff text (use INSTEAD of `content`). For WAF-bypass on large bodies. Server decodes before storing.
date	string	optional	Optional override date (YYYY-MM-DD). Defaults to today in server timezone.
time	string	optional	Optional time-of-day suffix in HHMM 24h format (KST), e.g. '1555'. Appended to the topic slug so multiple handoffs on the same day stay distinguishable. Omit for once-per-day saves.

Raw schema

{
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "description": "Project slug, e.g. 'logi', 'ainote', 'krx_ai'. Lowercase, no spaces."
    },
    "topic": {
      "type": "string",
      "description": "Short topic slug for this handoff, e.g. 'phase-d-port', 'oauth-fix'. Lowercase-hyphen."
    },
    "content": {
      "type": "string",
      "description": "Full handoff text. Should follow the session-handoff skill template (현재 상태 / 작업 위치 / 수정 파일 / 결정 사항 / 다음 STEP / 알려진 이슈). WAF-bypass tip: prefix the string with '__B64__:' followed by base64-encoded payload to bypass Render/Cloudflare edge WAF for large bodies (~10KB+) that get false-positive blocked as SQLi/cmd-injection."
    },
    "content_b64": {
      "type": "string",
      "description": "Optional: base64-encoded handoff text (use INSTEAD of `content`). For WAF-bypass on large bodies. Server decodes before storing."
    },
    "date": {
      "type": "string",
      "description": "Optional override date (YYYY-MM-DD). Defaults to today in server timezone."
    },
    "time": {
      "type": "string",
      "description": "Optional time-of-day suffix in HHMM 24h format (KST), e.g. '1555'. Appended to the topic slug so multiple handoffs on the same day stay distinguishable. Omit for once-per-day saves."
    }
  },
  "required": [
    "project",
    "topic",
    "content"
  ]
}

handoff_list

List session handoff notes saved in the primary vault under handoffs/, most-recent first. v2 frontmatter fields (status / has_blockers / tags / task_type) can be filtered server-side and are exposed in each entry without fetching the body. Read-only: entries older than 7 days are filtered out of results (a daily server-side cleanup job permanently deletes them).

Parameters7

project	string	optional	Optional project filter, e.g. 'logi' to list only logi-* handoffs.
limit	integer	optional	Max entries to return (default 50).
status	string	optional	v2 only: filter by frontmatter status (e.g. 'in_progress', 'paused', 'completed', 'blocked'). v1 handoffs without frontmatter are excluded when this filter is set.
has_blockers	boolean	optional	v2 only: filter by frontmatter has_blockers (true/false).
task_type	string	optional	v2 only: filter by frontmatter task_type (e.g. 'feature', 'bugfix', 'refactor', 'research', 'ops').
tags	array	optional	v2 only: AND match — entries must contain ALL given tags. Example: ['auth', 'mobile'].
since	string	optional	ISO8601 timestamp — only entries with updated_at >= since are returned.

Raw schema

{
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "description": "Optional project filter, e.g. 'logi' to list only logi-* handoffs."
    },
    "limit": {
      "type": "integer",
      "description": "Max entries to return (default 50)."
    },
    "status": {
      "type": "string",
      "description": "v2 only: filter by frontmatter status (e.g. 'in_progress', 'paused', 'completed', 'blocked'). v1 handoffs without frontmatter are excluded when this filter is set."
    },
    "has_blockers": {
      "type": "boolean",
      "description": "v2 only: filter by frontmatter has_blockers (true/false)."
    },
    "task_type": {
      "type": "string",
      "description": "v2 only: filter by frontmatter task_type (e.g. 'feature', 'bugfix', 'refactor', 'research', 'ops')."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "v2 only: AND match — entries must contain ALL given tags. Example: ['auth', 'mobile']."
    },
    "since": {
      "type": "string",
      "description": "ISO8601 timestamp — only entries with updated_at >= since are returned."
    }
  }
}

handoff_get

Retrieve a session handoff by project + topic. If date is omitted, returns the most recent matching handoff. Pass `time` (HHMM, KST) to fetch a specific same-day save when multiple exist. Read-only: handoffs older than 7 days are not returned (a daily server-side cleanup job permanently deletes them).

Parameters4

project	string	required	Project slug used at handoff_save time.
topic	string	required	Topic slug used at handoff_save time.
date	string	optional	Optional YYYY-MM-DD. Omit for latest.
time	string	optional	Optional HHMM (24h, KST) — same value passed at save time. Required to disambiguate when multiple handoffs share the same project/topic/date.

Raw schema

{
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "description": "Project slug used at handoff_save time."
    },
    "topic": {
      "type": "string",
      "description": "Topic slug used at handoff_save time."
    },
    "date": {
      "type": "string",
      "description": "Optional YYYY-MM-DD. Omit for latest."
    },
    "time": {
      "type": "string",
      "description": "Optional HHMM (24h, KST) — same value passed at save time. Required to disambiguate when multiple handoffs share the same project/topic/date."
    }
  },
  "required": [
    "project",
    "topic"
  ]
}

memory_search

Search your memory (dev docs / papers + vault markdown files) and get ranked snippets with IDs. COST PRINCIPLE: search returns snippets only; call memory_get for full content. MODES: - keyword (default): hybrid keyword + semantic match across title/path/content - latest_state: most recent memory, preferring entries saved with memory_type='state' (falls back to plain recency when no typed entries exist) Returns { found: false, message: "no memory found" } when nothing matches — treat that as a definitive empty signal and stop searching (do not guess).

Parameters4

query	string	required	Search text (e.g. 'render deploy key', 'ainote jwt'). May be blank only in latest_state mode.
mode	string	optional	keyword (default) or latest_state
sources	array	optional	Memory stores to search. Default: both.
limit	integer	optional	Max results (default 10, max 20)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search text (e.g. 'render deploy key', 'ainote jwt'). May be blank only in latest_state mode."
    },
    "mode": {
      "type": "string",
      "enum": [
        "keyword",
        "latest_state"
      ],
      "description": "keyword (default) or latest_state"
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "papers",
          "vault"
        ]
      },
      "description": "Memory stores to search. Default: both."
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 10, max 20)"
    }
  },
  "required": [
    "query"
  ]
}

memory_get

Fetch the full content of ONE memory item found via memory_search. source='paper' requires `id`; source='vault_file' accepts `id` or `path`. Only the authenticated user's own items are accessible. Returns { found: false } when the item does not exist (or belongs to another user).

Parameters3

source	string	required	Which store the item lives in (use the `source` field from memory_search results)
id	string	optional	Item ID returned by memory_search
path	string	optional	vault_file only: file path inside the vault (e.g. 'global/MEMORY.md')

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "paper",
        "vault_file"
      ],
      "description": "Which store the item lives in (use the `source` field from memory_search results)"
    },
    "id": {
      "type": "string",
      "description": "Item ID returned by memory_search"
    },
    "path": {
      "type": "string",
      "description": "vault_file only: file path inside the vault (e.g. 'global/MEMORY.md')"
    }
  },
  "required": [
    "source"
  ]
}

graph_get_node

Read a live env_sync graph node and its per-field LWW state. Lookup by node_id OR (alias + node_type).

Parameters3

node_id	string	optional
alias	string	optional
node_type	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "node_id": {
      "type": "string",
      "format": "uuid"
    },
    "alias": {
      "type": "string",
      "maxLength": 128
    },
    "node_type": {
      "type": "string",
      "enum": [
        "skill",
        "hook",
        "mcp_server",
        "secret",
        "setting_fragment"
      ]
    }
  },
  "oneOf": [
    {
      "required": [
        "node_id"
      ]
    },
    {
      "required": [
        "alias",
        "node_type"
      ]
    }
  ],
  "additionalProperties": false
}

graph_list_nodes

List live env_sync graph nodes for the calling user with optional node_type and HLC-since filters.

Parameters4

node_type	string	optional
updated_since_hlc	string	optional
limit	integer	optional
cursor	string	optional	Opaque cursor (created_at ISO + id) from previous page's next_cursor

Raw schema

{
  "type": "object",
  "properties": {
    "node_type": {
      "type": "string",
      "enum": [
        "skill",
        "hook",
        "mcp_server",
        "secret",
        "setting_fragment"
      ]
    },
    "updated_since_hlc": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "default": 100
    },
    "cursor": {
      "type": "string",
      "description": "Opaque cursor (created_at ISO + id) from previous page's next_cursor"
    }
  },
  "additionalProperties": false
}

graph_add_entity

Create a new env_sync graph node (skill/hook/mcp_server/secret/setting_fragment). Same-alias collisions open a conflict bucket — no silent overwrite.

Parameters5

node_type	string	required
alias	string	required
payload	object	required
device_id	string	required
client_hlc	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "node_type": {
      "type": "string",
      "enum": [
        "skill",
        "hook",
        "mcp_server",
        "secret",
        "setting_fragment"
      ]
    },
    "alias": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "payload": {
      "type": "object"
    },
    "device_id": {
      "type": "string",
      "format": "uuid"
    },
    "client_hlc": {
      "type": "string"
    }
  },
  "required": [
    "node_type",
    "alias",
    "payload",
    "device_id"
  ],
  "additionalProperties": false
}

graph_update_entity

Per-field LWW update for an env_sync graph node. Identity-immutable field mismatches open a conflict bucket (no partial writes).

Parameters4

node_id	string	required
device_id	string	required
client_hlc	string	optional
field_updates	array	required

Raw schema

{
  "type": "object",
  "properties": {
    "node_id": {
      "type": "string",
      "format": "uuid"
    },
    "device_id": {
      "type": "string",
      "format": "uuid"
    },
    "client_hlc": {
      "type": "string"
    },
    "field_updates": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "field",
          "value",
          "client_hlc"
        ],
        "properties": {
          "field": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "value": {},
          "client_hlc": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "required": [
    "node_id",
    "device_id",
    "field_updates"
  ],
  "additionalProperties": false
}

graph_soft_delete

Soft-delete an env_sync graph node (sets deleted_at; .live scope hides it from reads). Idempotent — re-deleting a deleted node is a no-op success.

Parameters3

node_id	string	required
device_id	string	required
client_hlc	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "node_id": {
      "type": "string",
      "format": "uuid"
    },
    "device_id": {
      "type": "string",
      "format": "uuid"
    },
    "client_hlc": {
      "type": "string"
    }
  },
  "required": [
    "node_id",
    "device_id"
  ],
  "additionalProperties": false
}

env_sync.device_enroll

Complete device enrollment by exchanging a one-shot enrollment_token for a registered device row with the device's age public key.

Parameters4

alias	string	required
age_pubkey	string	required
enrollment_token	string	required
capabilities	object	optional

Raw schema

{
  "type": "object",
  "properties": {
    "alias": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "age_pubkey": {
      "type": "string",
      "pattern": "^age1[a-z0-9]{58}$"
    },
    "enrollment_token": {
      "type": "string",
      "minLength": 16
    },
    "capabilities": {
      "type": "object",
      "properties": {
        "os": {
          "type": "string",
          "maxLength": 32
        },
        "claude_code_version": {
          "type": "string",
          "maxLength": 32
        },
        "transports": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "alias",
    "age_pubkey",
    "enrollment_token"
  ],
  "additionalProperties": false
}

env_sync.device_list

List enrolled devices for the calling user. Each entry includes age pubkey, capabilities, last_sync_at.

Parameters1

include_stale

boolean

optional

Raw schema

{
  "type": "object",
  "properties": {
    "include_stale": {
      "type": "boolean",
      "default": true
    }
  },
  "additionalProperties": false
}

env_sync.device_request_secret_share

Share existing secrets with a newly enrolled device by uploading re-encrypted ciphertexts. Plaintext never transits.

Parameters4

target_device_id	string	required
device_id	string	required	The existing device performing the re-encryption (must own access to all secret_node_ids).
secret_shares	array	required
client_hlc	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "target_device_id": {
      "type": "string",
      "format": "uuid"
    },
    "device_id": {
      "type": "string",
      "format": "uuid",
      "description": "The existing device performing the re-encryption (must own access to all secret_node_ids)."
    },
    "secret_shares": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "secret_node_id",
          "re_encrypted_ciphertext_b64"
        ],
        "properties": {
          "secret_node_id": {
            "type": "string",
            "format": "uuid"
          },
          "re_encrypted_ciphertext_b64": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1048576
          }
        },
        "additionalProperties": false
      }
    },
    "client_hlc": {
      "type": "string"
    }
  },
  "required": [
    "target_device_id",
    "secret_shares",
    "device_id"
  ],
  "additionalProperties": false
}

env_sync.secret_push

Push a new client-encrypted secret. Ciphertext only — server never sees plaintext. Recipients must include the pushing device's own pubkey.

Parameters6

alias	string	required
kind	string	required
ciphertext_b64	string	required
recipients	array	required
device_id	string	required
client_hlc	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "alias": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "kind": {
      "type": "string",
      "enum": [
        "api_key",
        "oauth_token",
        "private_key",
        "passphrase"
      ]
    },
    "ciphertext_b64": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1048576
    },
    "recipients": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "pattern": "^age1[a-z0-9]{58}$"
      }
    },
    "device_id": {
      "type": "string",
      "format": "uuid"
    },
    "client_hlc": {
      "type": "string"
    }
  },
  "required": [
    "alias",
    "kind",
    "ciphertext_b64",
    "recipients",
    "device_id"
  ],
  "additionalProperties": false
}

env_sync.secret_pull

Pull an encrypted secret blob. Response is ciphertext_b64 only — server never sees and never returns plaintext.

Parameters2

node_id	string	optional
alias	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "node_id": {
      "type": "string",
      "format": "uuid"
    },
    "alias": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "oneOf": [
    {
      "required": [
        "node_id"
      ]
    },
    {
      "required": [
        "alias"
      ]
    }
  ],
  "additionalProperties": false
}

env_sync.secret_rotate

Rotate a secret: soft-delete the old node, create a new live node with the same alias and the new ciphertext+recipients. 7-day grace before hard delete of old ciphertext bytes.

Parameters5

node_id	string	required
new_ciphertext_b64	string	required
new_recipients	array	required
device_id	string	required
client_hlc	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "node_id": {
      "type": "string",
      "format": "uuid"
    },
    "new_ciphertext_b64": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1048576
    },
    "new_recipients": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "pattern": "^age1[a-z0-9]{58}$"
      }
    },
    "device_id": {
      "type": "string",
      "format": "uuid"
    },
    "client_hlc": {
      "type": "string"
    }
  },
  "required": [
    "node_id",
    "new_ciphertext_b64",
    "new_recipients",
    "device_id"
  ],
  "additionalProperties": false
}

env_sync_txn_push

Ingest a batched envelope of client-recorded env_sync mutations. HLC-skew gated, partial-success on conflict.

Parameters1

operations

array

required

Raw schema

{
  "type": "object",
  "properties": {
    "operations": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "object",
        "required": [
          "tool",
          "args",
          "hlc"
        ],
        "properties": {
          "tool": {
            "type": "string"
          },
          "args": {
            "type": "object"
          },
          "hlc": {
            "type": "string"
          },
          "client_txn_id": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "required": [
    "operations"
  ],
  "additionalProperties": false
}

env_sync_txn_pull

Paginated read of env_sync transaction log, HLC-ordered. Read-only; filterable by since_hlc + op.

Parameters4

since_hlc	string	optional
op	string	optional
limit	integer	optional
cursor	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "since_hlc": {
      "type": "string"
    },
    "op": {
      "type": "string",
      "enum": [
        "push",
        "install",
        "uninstall",
        "reconcile",
        "migrate",
        "rollback"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "cursor": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

env_sync_txn_rollback

Inverse-apply a prior env_sync transaction. Safety gates: ownership, idempotency, descendant-conflict (force opt-out).

Parameters3

txn_id	string	required
include_descendants	boolean	optional
force	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "txn_id": {
      "type": "string",
      "format": "uuid"
    },
    "include_descendants": {
      "type": "boolean",
      "default": false
    },
    "force": {
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "txn_id"
  ],
  "additionalProperties": false
}

env_sync.heartbeat_ping

Device heartbeat ping. Updates last_sync_at + capabilities, triggers fast-path drift recheck if installed-set hashes changed.

Parameters8

device_id	string	required
installed_skills_hash	string	required
installed_hooks_hash	string	required
installed_mcp_servers_hash	string	optional
installed_skills	array	optional
installed_hooks	array	optional
claude_code_version	string	optional
os	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "string",
      "format": "uuid"
    },
    "installed_skills_hash": {
      "type": "string",
      "minLength": 64,
      "maxLength": 64
    },
    "installed_hooks_hash": {
      "type": "string",
      "minLength": 64,
      "maxLength": 64
    },
    "installed_mcp_servers_hash": {
      "type": "string",
      "minLength": 64,
      "maxLength": 64
    },
    "installed_skills": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "maxItems": 2000
    },
    "installed_hooks": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "maxItems": 2000
    },
    "claude_code_version": {
      "type": "string",
      "maxLength": 32
    },
    "os": {
      "type": "string",
      "maxLength": 32
    }
  },
  "required": [
    "device_id",
    "installed_skills_hash",
    "installed_hooks_hash"
  ],
  "additionalProperties": false
}

env_sync.drift_status

Cross-device drift report. Lists skills present on one device but missing on another, with dwell time.

Parameters1

device_id

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}

env_sync.sync_status

User-level vault health snapshot: node counts, pending conflicts, last transaction, device liveness.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Install

Tools (52)

list_taskscreate_taskupdate_taskdelete_tasklist_categorieslist_paperslist_dev_docsget_dev_doc

Configuration

Environment variables

AINOTE_API_KEYrequiredsecret

64-character ainote MCP key. Issue one via `npx @ainote/mcp signup` (RFC 8628 device flow), or in a Claude session by calling signup_and_get_key, or at https://app.ainote.dev -> Settings -> MCP keys.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "ainote": {
      "command": "npx",
      "args": [
        "-y",
        "@ainote/mcp@1.3.2"
      ],
      "env": {
        "AINOTE_API_KEY": "<YOUR_AINOTE_API_KEY>"
      }
    }
  }
}

MCP Server: io.github.seunghan91/ainote

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

list_tasks

create_task

update_task

delete_task

list_categories

list_papers

list_dev_docs

get_dev_doc

create_dev_doc

update_dev_doc

pull_dev_docs

delete_dev_doc

list_dev_categories

signup_and_get_key

login_and_get_key

get_setup_guide

vault_list

vault_create

vault_clone

vault_connect_status

vault_sync

sync_push

sync_push_batch

sync_pull

sync_list

sync_delete

sync_merge

sync_diff

sync_pending_conflicts

sync_audit_layer5

handoff_save

handoff_list

handoff_get

memory_search

memory_get

graph_get_node

graph_list_nodes

graph_add_entity

graph_update_entity

graph_soft_delete

env_sync.device_enroll

env_sync.device_list

env_sync.device_request_secret_share

env_sync.secret_push

env_sync.secret_pull

env_sync.secret_rotate

env_sync_txn_push

env_sync_txn_pull

env_sync_txn_rollback

env_sync.heartbeat_ping

env_sync.drift_status

env_sync.sync_status

Install

Configuration

Related servers