Memory stores

A memory store is a place where an agent keeps what it has learned so it can use it in later sessions: a customer’s preferences, the outcome of a past ticket, facts about a project. Without one, every session starts from nothing except the agent’s instructions.

Memory is opt-in. You create a store, attach it to an agent definition, and the agent gets two built-in tools to use it: one to search memories and one to write them. You can also read, add, correct and delete memories yourself through the API, which is how you seed a store, review what an agent remembered, and meet deletion requests.

When to use it

How scoping works

Each memory carries a scope string that you choose, such as customer:4821 or team:support. When a session starts, you pass memory_scope on POST /v1/sessions; the agent then reads and writes only memories with that scope (plus memories with the scope global, which it can read but not write unless the store allows it). One store can therefore serve thousands of customers without one customer’s memories reaching another’s session.

Endpoints

Base URL https://app.syntic.ai/v1 (the paths above already include /v1). Authenticate with a private key and send syntic-beta: agents-2026-11-01. Stores belong to the key’s workspace.

The store object

{
  "id": "mem_01JC1A3C5E7G9J1L3N5Q",
  "type": "memory_store",
  "name": "support-customers",
  "description": "What the support agents know about each customer.",
  "agent_write": "scoped",
  "max_memories_per_scope": 500,
  "default_ttl_days": 365,
  "memory_count": 18342,
  "created_at": "2026-11-02T12:00:00Z"
}

The memory object

{
  "id": "mmr_01JC8D1F3H5K7M9P1R3T",
  "store_id": "mem_01JC1A3C5E7G9J1L3N5Q",
  "scope": "customer:4821",
  "content": "Prefers replies by email, not phone. Has asked twice about bulk discounts.",
  "tags": ["preference"],
  "source": { "kind": "agent", "session_id": "sesn_01JC7M2K4P6R8T0V2X4Z", "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y" },
  "created_at": "2026-11-05T10:00:15Z",
  "updated_at": "2026-11-05T10:00:15Z",
  "expires_at": "2027-11-05T10:00:15Z"
}

content is plain text up to 4,000 characters. source.kind is agent or api, so you can always tell what the agent wrote from what you seeded.

Add a memory

POST /v1/memory_stores/{store_id}/memories with scope (required), content (required), and optional tags (up to 10) and expires_at.

Search

POST /v1/memory_stores/{store_id}/memories/search with query (required), scope (required, or "*" for all scopes when reviewing), limit (1 to 50, default 10) and optional tags. Results come back with a score from 0 to 1, highest first. This is the same search the agent’s built-in tool uses.

# Seed a memory, then search for it
curl -sS https://app.syntic.ai/v1/memory_stores/mem_01JC1A3C5E7G9J1L3N5Q/memories \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: agents-2026-11-01" \
  -d '{"scope": "customer:4821", "content": "Account manager is Dana Lee.", "tags": ["account"]}'
 
curl -sS https://app.syntic.ai/v1/memory_stores/mem_01JC1A3C5E7G9J1L3N5Q/memories/search \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: agents-2026-11-01" \
  -d '{"scope": "customer:4821", "query": "who looks after this account?"}'

const base = 'https://app.syntic.ai/v1/memory_stores/mem_01JC1A3C5E7G9J1L3N5Q'
const headers = {
  Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
  'Content-Type': 'application/json',
  'syntic-beta': 'agents-2026-11-01',
}
 
await fetch(`${base}/memories`, {
  method: 'POST', headers,
  body: JSON.stringify({ scope: 'customer:4821', content: 'Account manager is Dana Lee.', tags: ['account'] }),
})
 
const hits = await (await fetch(`${base}/memories/search`, {
  method: 'POST', headers,
  body: JSON.stringify({ scope: 'customer:4821', query: 'who looks after this account?' }),
})).json()
console.log(hits.data.map((m) => [m.score, m.content]))

import os, requests
 
BASE = "https://app.syntic.ai/v1/memory_stores/mem_01JC1A3C5E7G9J1L3N5Q"
H = {"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}", "syntic-beta": "agents-2026-11-01"}
 
requests.post(f"{BASE}/memories", headers=H, json={
    "scope": "customer:4821", "content": "Account manager is Dana Lee.", "tags": ["account"],
}).raise_for_status()
 
hits = requests.post(f"{BASE}/memories/search", headers=H, json={
    "scope": "customer:4821", "query": "who looks after this account?",
}).json()
for m in hits["data"]:
    print(m["score"], m["content"])

Attaching a store to an agent

Add the store’s id to memory_store_ids on the agent definition and pass memory_scope when you start each session. The agent then has two tools:

Both calls appear as memory steps in the run’s traces, so you can see exactly what was read and written.

Deletion and compliance

• DELETE .../memories/{id} removes one memory immediately from search and within 24 hours from backups.
• POST .../memories/delete_scope with {"scope": "customer:4821"} removes everything about one subject; use it for erasure requests. Returns the number deleted.
• POST .../export with an optional scope writes a JSONL file and returns its file_id, for access requests.
• Zero data retention: organizations with zero data retention cannot create memory stores unless an Owner turns on Allow agent memory in organization settings, which is recorded in the audit log. See Data retention.

Errors

Errors use the error envelope.

Limits and billing

Stored memories are free up to 100,000 per workspace, then billed per thousand memories per month. Searches made by agents are included in the session’s cost; searches through the API are free. Rates appear on Pricing at launch.

Build notes for the platform team

• Back stores with the existing memory service, adding a workspace_id and scope on every row and enforcing them in every query.
• Every write records source; agent writes record the session and agent ids.
• Export and scope deletion must also cover the search index, not only the primary table.

Related

• Agent definitions API
• Sessions
• Data retention