feat: add webhook thought ingestion

2026-07-15 04:24:23 +02:00
parent 5718685c40
commit fe82678280
7 changed files with 392 additions and 13 deletions
@@ -74,6 +74,38 @@ The AMCS directory is used to store configuration and code for the Avalon Memory
 | `describe_tools` | List all available MCP tools with names, descriptions, categories, and model-authored usage notes; call this at the start of a session to orient yourself |
 | `annotate_tool` | Persist your own usage notes for a specific tool; notes are returned by `describe_tools` in future sessions |

+## Webhook ingestion
+
+External automation can create thoughts without speaking MCP by posting JSON to `POST /webhooks/thoughts`. The endpoint is protected by the same AMCS authentication middleware as MCP and file uploads, so pass one configured API key via `x-brain-key`, an authorization bearer token header, or another enabled auth method.
+
+Example:
+
+```bash
+curl -X POST http://localhost:8080/webhooks/thoughts \
+  -H 'Content-Type: application/json' \
+  -H 'x-brain-key: <api-key>' \
+  -H 'Idempotency-Key: n8n-run-123' \
+  -d '{
+    "content": "External system observed build failure on main",
+    "project": "amcs",
+    "source": "n8n",
+    "type": "task",
+    "topics": ["ci", "webhook"],
+    "metadata": {"workflow": "ci-monitor", "run_id": "123"}
+  }'
+```
+
+Payload fields:
+
+- `content` is required and becomes the thought content.
+- `project` is optional; when present it must match an existing AMCS project.
+- `source`, `type`, `topics`, `people`, `action_items`, and `dates_mentioned` are normalized into the standard thought metadata schema. Unknown `type` values fall back to `observation`.
+- `metadata` or `source_metadata` may contain safe source-specific JSON values; unsupported values and overly deep objects are dropped rather than persisted.
+- `idempotency_key` or the `Idempotency-Key` header can be supplied to make repeated webhook deliveries return the existing thought with `duplicate: true`.
+- `external_id` is stored under `metadata.webhook.external_id` for source-side traceability.
+
+Successful new ingestion returns `201` with the created thought. Duplicate idempotency-key delivery returns `200` and the previously created thought. Invalid JSON, missing content, missing/unknown projects, or unauthenticated requests are rejected before persistence. Metadata and embedding enrichment are queued after the thought is stored.
+
 ## Learnings

 Learnings are curated, structured memory records for durable insights you want to keep distinct from raw thoughts. Use them for normalized lessons, decisions, and evidence-backed findings that should be easy to retrieve and review over time.