replace_labels
The atomic label swap. Remove one label or many, add one label or many — all in a single operation with no risk of partial state. Built for workflows where label integrity matters.
Parameters #
| Parameter | Type | Required | Description |
|---|---|---|---|
memory_id | number | Yes | The ID of the memory to update |
target | string | Yes | Label(s) to find and remove (comma-separated, case-insensitive) |
new | string | Yes | Label(s) to add in their place (comma-separated, preserves case) |
Examples #
# Simple one-to-one swap
replace_labels(memory_id: 42, target: "draft", new: "approved")
# One-to-many — expand a placeholder into real labels
replace_labels(memory_id: 42, target: "wip", new: "architecture,decision,2026-03-01")
# Many-to-many — restructure labeling entirely
replace_labels(memory_id: 42, target: "old-label,another-old", new: "new-label,refined,updated")
Why Atomic Matters #
Before replace_labels, a label state transition required two separate calls:
del_labels(memory_id: 42, labels: "wip") # call 1 — label gone
add_labels(memory_id: 42, labels: "approved") # call 2 — if this fails, label is just... gone
A crash or timeout between call 1 and call 2 leaves the memory in an undefined state — no wip, no approved, no way to know what happened.
replace_labels does both in one transaction. Either it succeeds completely, or nothing changes.
Power Combinations #
Label enrichment cron — the killer use case. A background process retrieves unprocessed memories (identified by a nonce label), sends content to a tiny LLM for semantic labeling, then atomically swaps the nonce for real topic labels:
# Memory stored with nonce: labels = ["52868312778495", "2026-03-01"]
# LLM returns: "plugin-dev,memory-system,session-management"
replace_labels(
memory_id: 101,
target: "52868312778495",
new: "plugin-dev,memory-system,session-management"
)
# Result: labels = ["plugin-dev", "memory-system", "session-management", "2026-03-01"]
# Nonce gone. Real labels in. Date preserved. One operation.
Workflow state machine — move memories through defined states cleanly:
# Draft → review
replace_labels(memory_id: 101, target: "draft", new: "in-review")
# Review → approved
replace_labels(memory_id: 101, target: "in-review", new: "approved,completed")
Correction without loss — fix a mislabeled memory while keeping everything else intact:
replace_labels(memory_id: 101, target: "wrong-topic", new: "correct-topic")