REST API
A plain-REST mirror of the memory tools under /api/v1. Both transports call
the same service, so REST and MCP are behaviour-identical — same provenance, same trust model.
Interactive reference. Open Swagger UI at
/api/docs to try every endpoint in the browser (click Authorize, paste your agt_… key, then Try it out). The raw spec is at /openapi.json.
Authentication
Memory endpoints take a per-agent key: Authorization: Bearer agt_…. Key-provisioning endpoints
(/api/v1/keys) take the shared master key instead. A missing/invalid key returns
401; bad input returns 422; a memory id that isn’t yours returns 404
(ids are scoped per agent — a cross-agent id is simply not found).
Endpoints
| Method & path | Does | Tool |
|---|---|---|
POST /api/v1/memories | Remember | memory_remember |
POST /api/v1/memories/recall | Semantic recall | memory_recall |
GET /api/v1/memories | List / audit | memory_list |
POST /api/v1/memories/{id}/supersede | Correct (new replaces old) | memory_supersede |
POST /api/v1/memories/{id}/forget | Tombstone | memory_forget |
POST /api/v1/memories/{id}/observe | Fresh observation | memory_observe |
POST /api/v1/keys | Provision a key (master key) | — |
POST /api/v1/keys/revoke | Revoke a key (master key) | — |
Remember → recall
TOK=agt_…
# remember (sourced => stored as a fact)
curl -s -X POST https://syntheticmem.com/api/v1/memories \
-H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
-d '{"content":"Deploys restart php8.4-fpm.","source":"runbook"}'
# -> 200 {"id":42,"status":"fact","source":"runbook","ephemeral":false,"expiry":"permanent",…}
# recall (facts first, with provenance + trust)
curl -s -X POST https://syntheticmem.com/api/v1/memories/recall \
-H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
-d '{"query":"what happens to php-fpm on deploy?"}'
# -> 200 {"query":"…","results":[{"id":42,"status":"fact","similarity":0.89,"trust":"fact: …",…}]}
Listing
curl -s "https://syntheticmem.com/api/v1/memories?namespace=proj&status=fact&limit=20" \
-H "Authorization: Bearer $TOK"
# -> 200 {"results":[ … ]}