memory_edit

One tool, three editing modes. The mode is determined automatically by which parameters you provide. Only memory_id is required — omitted fields are left unchanged.

Mode 1: Content Replace

The replacement content follows the same quality rules as memory_add: first 50 characters are an executive summary, the text must stand alone with no conversational context, and it should include why alongside the fact. The new topics and macro_topics arrays replace the existing arrays wholesale — they are not merged. To add one topic, include every existing topic plus the new one.

memory_edit({
  memory_id: "a1b2c3d4-...",
  content: "PostgreSQL max_connections default is 100 — raise to 200 for connection-pooled apps",
  topics: ["postgres", "connections", "config", "pooling"],
  macro_topics: ["infrastructure"]
})

Mode 2: Metadata Patch

Common uses: reclassifying a memory's type (e.g., fact to decision), adding a topic so it surfaces in new searches, or setting an expiry date on time-bound information. Since topics and macro_topics are replaced wholesale, always include the full desired set.

memory_edit({
  memory_id: "a1b2c3d4-...",
  type: "decision",
  topics: ["auth", "jwt", "session", "backend"]
})

Mode 3: Task Surgery

toggle

Flip checkboxes by 0-based index. Pass an array of integers — [0, 2] toggles the 1st and 3rd checkboxes. A checked box becomes unchecked; an unchecked box becomes checked. The server processes toggles in reverse index order to preserve character positions. No re-embedding.

// Mark steps 0 and 2 as complete
memory_edit({
  memory_id: "a1b2c3d4-...",
  toggle: [0, 2]
})

set_status

Set the task's workflow status. Valid values: pending, active, blocked, review, done. No re-embedding. The review status means work is complete and awaiting human review.

Setting status to done automatically changes the memory's type from task to task_done. Reverting away from done changes the type back to task. You never set the type manually for this transition — it follows the status.

set_status can combine with toggle. A common pattern: toggle the last checkbox and set status to done in one call.

// Toggle final step and mark complete
memory_edit({
  memory_id: "a1b2c3d4-...",
  toggle: [4],
  set_status: "done"
})

add_steps

Append new checklist items. Each string becomes a - [ ] {step} checkbox line. Maximum 10 steps total including existing steps — not 10 new steps. If the task grows beyond 10 steps, split into multiple tasks with shared topics for grouping. Re-embeds because step text is part of the memory's semantic content.

remove_steps

Remove steps by 0-based index. Indices refer to the state before this call — if you remove indices [1, 3], both refer to positions in the original checklist, not positions after earlier removals. Re-embeds.

edit_step

Rewrite a single step's text while preserving its checkbox state (checked or unchecked). Pass an object with index (0-based) and text (new step text). Re-embeds.

// Rewrite step 2 without changing its checked/unchecked state
memory_edit({
  memory_id: "a1b2c3d4-...",
  edit_step: { index: 2, text: "Validate OAuth2 callback with PKCE" }
})

Step operations can combine with each other and with set_status

When multiple step operations appear in one call, the server applies them in a fixed order: edit_step first, then remove_steps, then add_steps, then set_status. All index references refer to the state before any mutations in this call.

Mutual exclusivity rules

The content parameter is a full rewrite. Surgical parameters operate on the existing content. Combining them would be ambiguous — the server rejects it with an explicit error.

The output Parameter

The output parameter works alongside toggle and set_status. It creates a new memory of type result, inheriting the task's topics and macro_topics. The task's short ID (first 8 characters of the UUID) is added as a topic, linking the result to the task for cluster discovery. When combined with toggle, the specific step index is encoded into the reference, so results can be rendered inline under their corresponding step.

The output text follows the same quality rules as memory_add: first 50 characters are the summary, one atomic finding per call, under 500 tokens. For multiple findings, call memory_add directly with the task's topics.

// Toggle step 1, record what was found
memory_edit({
  memory_id: "a1b2c3d4-...",
  toggle: [1],
  output: "OAuth2 callback uses PKCE with S256 — prevents auth code interception without client secret"
})

The output is stored in the same namespace as the task. If the task lives in a shared collection, the linked result is visible to everyone with collection access.

Design Rationale: Why Surgical Mode Exists

Task updates happen frequently during active development. Re-embedding on every checkbox toggle would create unnecessary vector churn and consume GPU cycles. Surgical mode keeps the embedding stable while the checklist evolves. Only content changes that alter the memory's meaning trigger re-embedding.

The distinction maps directly to what affects search quality. Toggling a checkbox from unchecked to checked does not change what the task is about — it changes where the task is in its lifecycle. The embedding should reflect the task's subject matter, not its progress. Status and checkbox state are metadata; step text and task descriptions are content.

Step modifications (add, remove, edit) sit in between. Adding a step like "Validate OAuth2 callback with PKCE" changes the task's semantic fingerprint — future searches for "PKCE" or "OAuth2" should find this task. Removing a step narrows the semantic scope. Both warrant re-embedding. The cost is justified because step content changes are less frequent than checkbox toggles and status transitions.