From 97ee66770ab049a6601f59061b46502dc9e45afd Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Mon, 2 Mar 2026 20:53:21 -0600
Subject: [PATCH] docs: add full CRUD API patterns to OpenBrain section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

REST endpoints (GET/PATCH/DELETE /v1/thoughts/{id}, bulk DELETE/GET
with filters) and updated MCP tools list to include get, update,
delete, delete_where, list_thoughts — all live in v0.1.0.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 TOOLS.md | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/TOOLS.md b/TOOLS.md
index b761a73..7c18af8 100644
--- a/TOOLS.md
+++ b/TOOLS.md
@@ -160,18 +160,32 @@ Configure in your credentials.json:
 ```bash
 source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials openbrain
 
-# Search by meaning
+# --- Read ---
+curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/recent?limit=5"
+curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/{id}"
+curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" \
+  "$OPENBRAIN_URL/v1/thoughts?source=agent-name&metadata_id=my-entity&limit=10"
+
+# --- Search ---
 curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
   -d '{"query": "your search", "limit": 5}' "$OPENBRAIN_URL/v1/search"
 
-# Capture a thought
+# --- Capture ---
 curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
   -d '{"content": "...", "source": "agent-name", "metadata": {}}' "$OPENBRAIN_URL/v1/thoughts"
 
-# Recent activity
-curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/recent?limit=5"
+# --- Update (re-embeds if content changes) ---
+curl -s -X PATCH -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"content": "updated text", "metadata": {"key": "val"}}' "$OPENBRAIN_URL/v1/thoughts/{id}"
 
-# Stats
+# --- Delete single ---
+curl -s -X DELETE -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/{id}"
+
+# --- Bulk delete by filter (source and/or metadata_id required) ---
+curl -s -X DELETE -H "Authorization: Bearer $OPENBRAIN_TOKEN" \
+  "$OPENBRAIN_URL/v1/thoughts?source=agent-name&metadata_id=my-entity"
+
+# --- Stats ---
 curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/stats"
 ```
 
@@ -183,7 +197,8 @@ python tools/openbrain_client.py recent --limit 5
 python tools/openbrain_client.py stats
 ```
 
-**MCP (Claude Code sessions):** When connected, `mcp__openbrain__capture/search/recent/stats` tools are available natively — prefer those over CLI when in a Claude session.
+**MCP (Claude Code sessions):** When connected, all CRUD tools are available natively:
+`capture`, `search`, `recent`, `stats`, `get`, `update`, `delete`, `delete_where`, `list_thoughts`
 
 **When to use openbrain (required for all agents):**