io.github.seunghan91/ainote

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.

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

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).

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.

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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.

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

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).

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).

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).

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.

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.

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.

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.

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

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.

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).

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).

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.

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.

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.

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.

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.

Legacy alias for listing files in the primary vault.

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).

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.

Legacy alias for pulling files from the primary vault.

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.

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.

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

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

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

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.

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.