updating-thoughts

# Updating Thoughts

## Overview

The core Open Brain MCP server captures and reads thoughts but cannot change
them. `update_thought` (the `open-brain-update-thought` connector) fills that
gap. Choosing *how* to update is the non-obvious part: tagging and rewriting
behave and cost differently, and the tool acts on a thought's **UUID**, which
it will not look up for you.

## When to Use

- Correcting or rewriting a thought's text
- Re-classifying or tagging it (status, review flags, cross-references)
- Annotating it without touching the wording

Not for: creating a thought (use capture), or removing one — if the thought is
outdated or wrong, prefer updating or tagging it `superseded` over deleting
(see the **deleting-thoughts** skill).

## Process

1. **Resolve the id first.** `update_thought` takes a UUID, not a description.
   Use `search_thoughts` / `list_thoughts` to find the target and confirm it is
   the right one. Never guess a UUID.
   - **Inspect before editing.** Before you overwrite anything, read the target's
     full content with `get_thought` (or the connector's `fetch` tool), and use
     `related_thoughts` to see what it connects to — so you don't clobber context
     other thoughts depend on. Tool names may carry a connector prefix; use
     whatever the environment exposes.
2. **Pick the mode:**
   - Tag / re-classify only → pass `metadata_patch` (shallow-merges keys; leaves
     content and unmentioned keys alone; **no re-embedding**).
   - Change the wording → pass `content` (replaces the text **and re-embeds** so
     semantic search stays accurate).
   - Both → pass both; they compose in one call.
3. **Guard read-modify-write (optional).** If you read the thought, reasoned,
   then write back — and other writers may exist — pass `if_unchanged_since` set
   to the `updated_at` you read. The write is rejected with `STALE_READ` if the
   row changed underneath you; re-fetch and retry.

## Quick Reference

| Goal | Field | Re-embeds? |
|------|-------|-----------|
| Add/change tags, status, links | `metadata_patch` | No |
| Rewrite the note text | `content` | Yes |
| Prevent a lost update | `if_unchanged_since` | — |

`metadata_patch` is a **merge, not a replace**: `{"status":"done"}` adds or
overwrites only `status` and leaves everything else in the metadata intact.

## Output

A confirmation naming the thought id, what changed (content replaced and
re-embedded, and/or metadata merged), and the new `updated_at`.

## Common Mistakes

- Using `content` just to add a tag — wastes an embedding call; use
  `metadata_patch`.
- Expecting `metadata_patch` to replace the whole metadata object — it merges.
- Skipping the search step and passing a half-remembered UUID.

## Notes

- A restricted/sensitive thought may refuse a content update by policy.
- Connector: `open-brain-update-thought`, auth via `?key=` or the `x-brain-key`
  header — the same `MCP_ACCESS_KEY` as your core Open Brain connector.