docs: fix drift in Memory Operations

[jack-arturo]

Automated docs-accuracy audit of reference/api/memory-operations. Two of these are copy-pasteable examples that fail against the current API.

Claim	Current state	Fix	Evidence
POST /memory/batch body is a bare JSON array — "Send the request body as a JSON array (not an object)", with both the schema block and the curl example showing [...]	The handler requires a JSON object: if not isinstance(payload, dict): abort(400, "JSON body with 'memories' array required"), then reads payload.get("memories", []). The documented request returns 400.	Schema block and curl example rewritten to {"memories": [...]}; the surrounding sentence now states the object requirement, the exact 400 message, and the non-empty constraint.	automem@8ff266e:automem/api/memory.py#L1130-L1140
Batch status codes: 413 Payload Too Large when batch exceeds 500	Oversized batches abort(400, "Batch size limit is 500 memories per request"). No code path returns 413. 503 is reachable (FalkorDB unavailable) but was undocumented.	413 row replaced with the real 503 row; the 400 row now enumerates every validation trigger including the >500 case. Added a note that validation is all-or-nothing (every entry is validated before any write).	automem@8ff266e:automem/api/memory.py#L1141-L1142, #L1264
"qdrant": "ok" in both the POST /memory and POST /memory/batch success responses	qdrant_result is only ever "stored", "failed", "queued", "unconfigured", or null. "ok" does not exist. The example also paired "ok" with "embedding_status": "queued", whose real partner is "queued".	Both examples set to "queued". Added a correlation table for the five real embedding_status/qdrant pairs, plus the enrichment queued/disabled values.	automem@8ff266e:automem/api/memory.py#L672-L726
Error envelope is {"error": "...", "field": "field_name"}; batch validation errors are {"error": "...", "index": 2}	The app-wide @app.errorhandler(Exception) returns {"status": "error", "code": <int>, "message": <description>} for every HTTPException and a generic 500 otherwise. Neither error nor field nor index is ever emitted.	Both error examples rewritten to the real envelope; noted that field/index detail rides in message, and that unhandled exceptions collapse to a generic 500.	automem@8ff266e:app.py#L471-L489
Source note pinned memory.py at ebcf5f16	The file has changed substantially since then (+306/−7), including the whole batch endpoint.	Repinned to 8ff266e.	git diff --stat ebcf5f16..8ff266e -- automem/api/memory.py

The three mcp-automem source-note links (src/index.ts, src/automem-client.ts, src/types.ts at 538721c) were not repinned — all three files are byte-identical between 538721c and 946f9e5, so those permalinks are still accurate.

Spot-checked and confirmed correct, left untouched: /memory/by-tag limit default 20 clamped to 1–200 and offset default 0; CLASSIFICATION_MODEL default gpt-4o-mini; RECALL_RELATION_LIMIT default 5; DELETE /memory/:id returning 404 for a missing memory; the summarized/original_length/summarized_length response fields; and the hierarchical tag-prefix behavior.

Verified against: automem@8ff266e62e65cb2e81719a765b05f64a2361a127
Verified against: mcp-automem@946f9e5ed1385b632efd2e5b250d064bcc4295e8

Questions

• The "Tagging Conventions (from platform templates)" table recommends a date component in tags ("2025-01") for five of five memory types. The shipped memory policy in mcp-automem explicitly forbids date-stamped tags ("no date-stamped tags"; use t_valid/t_invalid instead), and a prior audit flagged the same contradiction on best-practices/context-engineering. Left alone here because it spans several pages and reads like a deliberate policy change that hasn't propagated — worth a single coordinated fix rather than a per-page edit.
• POST /memory is documented as returning 201 Created, which matches the code, but the endpoint uses MERGE on the memory id. Storing with an explicit id that already exists therefore updates in place while still reporting 201. Intentional?

Unverified

• Client retry logic ("Network errors: retried up to 3 times (500ms, 1s, 2s delays)", "Timeout: 25 seconds"). Not re-derived from src/automem-client.ts this pass — the 538721c pin is current, so the numbers were taken as previously verified rather than re-checked.
• "reduces costs 40–50%" for embedding batching, and the "O(1) filtering" characterization of tag_prefixes — both are performance characterizations with no single code anchor.

Follow-ups

None — all discrepancies found on this page are fixed above, and the count is at the 5-fix cap.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying automem-website with    Cloudflare Pages

Latest commit:	01735bf
Status:	✅  Deploy successful!
Preview URL:	https://17c34fbb.automem-website.pages.dev
Branch Preview URL:	https://docs-audit-reference-api-mem-pelr.automem-website.pages.dev

View logs