docs: fix drift in Memory Operations

[jack-arturo]

Automated docs-accuracy audit of docs/reference/api/memory-operations. Five proven discrepancies, capped at the per-PR limit.

Supersedes stale #271 (opened 2026-07-29, never merged).

Claim	Current state	Fix	Evidence
POST /memory/batch takes a bare JSON array — "Send the request body as a JSON array (not an object)", with a matching curl -d '[...]' example	store_batch() calls abort(400, "JSON body with 'memories' array required") when the payload is not a dict, then reads payload.get("memories", []). Every documented batch call fails with 400 as written	Wrap the body in {"memories": [...]} in the schema block, the sentence, and the curl example	automem@42ba8b6:automem/api/memory.py#L1135
Oversize batch returns 413 Payload Too Large	The size guard is abort(400, "Batch size limit is 500 memories per request"). The string 413 does not appear anywhere in the automem package	Drop the 413 row; fold the batch-size and empty-array cases into the 400 row	automem@42ba8b6:automem/api/memory.py#L1142
Validation errors return {"error": "...", "index": 2}	The global handler in app.py returns {"status": "error", "code": <int>, "message": <description>} for every HTTPException. Neither error nor index is ever a response key	Show the real error envelope and the real message text	automem@42ba8b6:app.py#L471
MCP delete_memory takes memory_id (Required: Yes) and nothing else	The tool is two-mode: memory_id XOR tags, where tags bulk-deletes every memory matching any tag (exact, case-insensitive, no dry-run). Neither parameter is unconditionally required	Document both modes, with the bulk-delete warning the tool description carries	mcp-automem@92c2e33:src/index.ts#L1331
Tagging conventions table prescribes platform tags and YYYY-MM date tags (["ecommerce", "cursor", "2025-01", "decision"]); the MCP example tags 2025-01	The shipped memory policy forbids exactly these: "no lang/ prefixes, platform tags, or date-stamped tags" and "NO platform tag, NO [YYYY-MM]"	Rewrite the five rows as bare-tag patterns, add one sentence stating the rule, and drop the date tag from the MCP example	mcp-automem@92c2e33:src/memory-policy/shared.ts#L433, mcp-automem@92c2e33:src/memory-policy/shared.ts#L876

Verified against: automem@42ba8b61b7d0b24ecaeb7feb4ceef59f09fc7cd0
Verified against: mcp-automem@92c2e33cb932b71d0df35fdc250778c6a51257af

Checked and correct, left untouched: the POST /memory 201 response body (every field matches memory.py:718-732), the batch 201 response body, GET /memory/by-tag limit clamp (1–200, default 20) and offset, the DETACH DELETE + 404-on-missing behavior, gpt-4o-mini as the classification fallback, and the client retry contract (25s timeout, 3 retries at 500ms/1s/2s).

Questions

• The POST /memory optional-field table lists updated_at and last_accessed as accepted request fields. They are certainly returned in the response; I could not conclusively trace them as inbound fields on the single-store path, and getting it wrong either way would be worse than leaving it, so I did not touch the row.
• GET /memory/:id also returns 503 when the graph is unavailable and 500 on a query failure. The status-code table lists only 404 and 401 — plausibly a deliberate simplification to the codes a caller acts on, so left as-is.

Unverified

• The "Importance Scoring Guidelines" and "Typical Importance" ranges are editorial conventions with no counterpart in code; nothing to verify them against.
• The mermaid data-flow diagrams name internal helpers (_normalize_tag_list, _compute_tag_prefixes, _normalize_timestamp) that are wired through the app-helper runtime rather than defined in automem/api/memory.py. Names look right but I could not pin each to a definition site within this pass.

Follow-ups

• The MCP store_memory optional-parameter table omits type, confidence, id, t_valid, t_invalid, and the memories batch parameter, all of which the tool accepts.
• The source-file note pins automem/api/memory.py at ebcf5f1 and the three mcp-automem files at 538721c; both are valid permalinks but several audits behind.
• The endpoint table lists /recall in a page otherwise scoped to memory CRUD; it is documented in full on the Recall Operations page.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying automem-website with    Cloudflare Pages

Latest commit:	da0beb0
Status:	✅  Deploy successful!
Preview URL:	https://9f76f091.automem-website.pages.dev
Branch Preview URL:	https://docs-audit-reference-api-mem-hvgv.automem-website.pages.dev

View logs