Getting started
From zero to a recalled memory in about a minute — provision a key, connect a client, then remember and recall.
1. Provision an agent key
Each agent authenticates with its own agt_… bearer key. The key is shown once.
An agent only ever touches its own memories (a fail-closed scope — a cross-agent id is simply “not found”);
a namespace sub-scopes within an agent, e.g. one per project.
On the server (artisan)
php artisan syntheticmem:mcp-token my-agent --name=laptop --namespace=my-project # list keys: php artisan syntheticmem:mcp-token --list # revoke a key: php artisan syntheticmem:mcp-token --revoke=<key-id>
Remotely (master key over HTTP)
An operator holding SYNTHETICMEM_MASTER_KEY can mint a key via REST:
curl -s -X POST https://syntheticmem.com/api/v1/keys \
-H "Authorization: Bearer $SYNTHETICMEM_MASTER_KEY" \
-H 'Content-Type: application/json' \
-d '{"agent":"my-agent","label":"laptop","namespace_default":"my-project"}'
# -> {"token":"agt_…","agent":"my-agent","namespace_default":"my-project"}
POST /api/mcp/provision is still accepted and identical — /api/v1/keys is the REST-shaped alias.
2. Connect an MCP client
claude mcp add --transport http syntheticmem https://syntheticmem.com/api/mcp \ --header "Authorization: Bearer agt_…"
Or declare it in .mcp.json:
{ "mcpServers": { "syntheticmem": { "type": "http",
"url": "https://syntheticmem.com/api/mcp",
"headers": { "Authorization": "Bearer agt_…" } } } }
Works with any Streamable-HTTP MCP client — see Connect your agent for opencode, grok, and raw HTTP.
3. First remember + recall
Over MCP (JSON-RPC)
TOK=agt_…
curl -s -X POST https://syntheticmem.com/api/mcp \
-H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memory_remember",
"arguments":{"content":"Deploys restart php8.4-fpm.","source":"runbook"}}}'
curl -s -X POST https://syntheticmem.com/api/mcp \
-H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_recall",
"arguments":{"query":"what happens to php-fpm on deploy?"}}}'
Over REST
TOK=agt_…
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"}'
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?"}'
Recall never returns bare text: each hit carries full provenance (source, learned_at,
last_observed_at, hop_count, confidence, status, similarity)
plus a trust hint. Read Concepts next to understand why.