Memories API

Query and manage a character's memory of a specific player. Estuary automatically builds memory from conversations -- this API gives you read access to what the character remembers.

Base path: /api/agents/{agent_id}/players/{player_id}/memories

agent_id = character_id

The agent_id in the URL path is the same id returned by the Characters API.

For background on how memory works, see Memory System.

---

List Memories

GET /api/agents/{agent_id}/players/{player_id}/memories

Returns a paginated list of memories.

Query Parameters

Parameter	Type	Default	Description
memory_type	string	—	Filter by type: "episodic", "semantic", "emotional", "character_self"
status	string	"active"	Memory status filter
limit	integer	50	Results per page (1-200)
offset	integer	0	Number of results to skip
sort_by	string	"created_at"	Sort field: "created_at", "confidence", "last_accessed_at"
sort_order	string	"desc"	"asc" or "desc"

Response

{
  "memories": [
    {
      "id": "mem_abc123",
      "memoryType": "semantic",
      "content": "The user works as a software engineer at a startup in San Francisco",
      "confidence": 0.92,
      "createdAt": "2026-02-10T15:30:00",
      "lastAccessedAt": "2026-03-01T14:22:00"
    }
  ],
  "total": 87,
  "limit": 50,
  "offset": 0
}

Examples

# All memories
curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories" \
  -H "X-API-Key: est_your_api_key"

# Only semantic memories, sorted by confidence
curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories?memory_type=semantic&sort_by=confidence" \
  -H "X-API-Key: est_your_api_key"

const res = await fetch(
  `https://api.estuary-ai.com/api/agents/${agentId}/players/${playerId}/memories?memory_type=episodic&limit=20`,
  { headers: { "X-API-Key": "est_your_api_key" } }
);
const data = await res.json();
console.log(`${data.total} episodic memories`);

---

Memory Timeline

GET /api/agents/{agent_id}/players/{player_id}/memories/timeline

Returns memories grouped by date for timeline visualization.

Query Parameters

Parameter	Type	Default	Description
group_by	string	"day"	Grouping period: "day", "week", "month"
start_date	datetime	—	Filter memories after this date (ISO 8601)
end_date	datetime	—	Filter memories before this date (ISO 8601)

Response

{
  "timeline": [
    {
      "date": "2026-03-01",
      "memories": [ /* Memory objects */ ]
    },
    {
      "date": "2026-02-28",
      "memories": [ /* Memory objects */ ]
    }
  ],
  "totalMemories": 87,
  "groupBy": "day"
}

Example

curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories/timeline?group_by=week" \
  -H "X-API-Key: est_your_api_key"

---

Memory Stats

GET /api/agents/{agent_id}/players/{player_id}/memories/stats

Returns aggregate statistics about a player's memory.

Example

curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories/stats" \
  -H "X-API-Key: est_your_api_key"

---

Core Facts

GET /api/agents/{agent_id}/players/{player_id}/memories/core-facts

Returns the core facts the character knows about a player. Core facts are concise, structured statements (name, location, interests, etc.) always included in the LLM context.

Response

{
  "coreFacts": [
    {
      "id": "fact_001",
      "userId": "user_abc",
      "agentId": "agent_xyz",
      "playerId": "player_xyz",
      "factKey": "name",
      "factValue": "Alex",
      "sourceMemoryId": "mem_abc123",
      "createdAt": "2026-02-10T15:30:00",
      "updatedAt": "2026-03-01T14:22:00"
    },
    {
      "id": "fact_002",
      "userId": "user_abc",
      "agentId": "agent_xyz",
      "playerId": "player_xyz",
      "factKey": "occupation",
      "factValue": "Software engineer at a startup",
      "sourceMemoryId": "mem_def456",
      "createdAt": "2026-02-12T10:00:00",
      "updatedAt": null
    }
  ]
}

Example

curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories/core-facts" \
  -H "X-API-Key: est_your_api_key"

---

Knowledge Graph

GET /api/agents/{agent_id}/players/{player_id}/memories/graph

Returns the memory knowledge graph: clustered memories, entities, and their relationships.

Query Parameters

Parameter	Type	Default	Description
include_entities	boolean	false	Include entity nodes and relationship edges
include_character_memories	boolean	false	Include the character's self-reflective memories

Response

{
  "nodes": [
    { "id": "user_player_xyz", "type": "user", "label": "player_xyz" },
    { "id": "cluster_0", "type": "cluster", "label": "Work & Career", "memoryCount": 12 },
    { "id": "mem_abc", "type": "memory", "label": "Works as a software engineer...", "memoryType": "semantic" },
    { "id": "ent_001", "type": "entity", "entityType": "person", "name": "Alex" }
  ],
  "edges": [
    { "source": "user_player_xyz", "target": "cluster_0", "type": "has_cluster" },
    { "source": "cluster_0", "target": "mem_abc", "type": "contains" },
    { "source": "mem_abc", "target": "ent_001", "type": "mentions" }
  ],
  "stats": {
    "totalMemories": 87,
    "totalEntities": 15,
    "clusterCount": 6,
    "clusters": { "Work & Career": 12, "Hobbies": 8 }
  },
  "stale": false
}

Node types

Type	Description
user	The player node (center of the graph)
cluster	A topic group containing related memories
memory	An individual memory
entity	A person, place, or thing mentioned in memories

Edge types

Type	Description
has_cluster	User → Cluster
contains	Cluster → Memory
mentions	Memory → Entity
relationship	Entity → Entity (with relationshipType and label)

Example

curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories/graph?include_entities=true" \
  -H "X-API-Key: est_your_api_key"

---

Search Memories

GET /api/agents/{agent_id}/players/{player_id}/memories/search

Semantic search across a player's memories using vector similarity.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query (1-500 chars)
limit	integer	No	Max results (1-100, default 20)

Response

{
  "results": [
    {
      "memory": {
        "id": "mem_abc",
        "memoryType": "episodic",
        "content": "The user talked about hiking in Rocky Mountain National Park last summer"
      },
      "score": 0.87,
      "similarityScore": 0.92
    }
  ],
  "query": "hiking trips",
  "total": 5
}

Field	Type	Description
memory	object	The matching memory object
score	number	Composite relevance score
similarityScore	number	Raw vector similarity score

Example

curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories/search?q=hiking%20trips&limit=5" \
  -H "X-API-Key: est_your_api_key"

const res = await fetch(
  `https://api.estuary-ai.com/api/agents/${agentId}/players/${playerId}/memories/search?q=favorite+foods&limit=10`,
  { headers: { "X-API-Key": "est_your_api_key" } }
);
const data = await res.json();
data.results.forEach((r) => {
  console.log(`[${r.score.toFixed(2)}] ${r.memory.content}`);
});

---

Delete Memories

DELETE /api/agents/{agent_id}/players/{player_id}/memories?confirm=true

Permanently deletes all memories for a player-character pair. Useful for GDPR compliance.

warning

The confirm=true query parameter is required. Requests without it return 400 Bad Request.

Response

{
  "message": "Deleted 87 records",
  "deletedCount": 87
}

Example

curl -X DELETE "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories?confirm=true" \
  -H "X-API-Key: est_your_api_key"