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: "fact", "preference", "relationship", "event", "emotional_state", "correction", "character_self", "spatial_change"
status	string	"active"	Memory status: "active", "superseded", "decayed", "deleted"
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": "fact",
      "content": "The user works as a software engineer at a startup in San Francisco",
      "confidence": 0.92,
      "status": "active",
      "source": "text_chat",
      "topic": "career",
      "secondaryTopics": ["location"],
      "sourceQuote": "I work as a software engineer at this startup in SF",
      "accessCount": 3,
      "createdAt": "2026-02-10T15:30:00",
      "lastAccessedAt": "2026-03-01T14:22:00",
      "extractedAt": "2026-02-10T15:31:00",
      "updatedAt": "2026-02-10T15:30:00"
    }
  ],
  "total": 87,
  "limit": 50,
  "offset": 0
}

Memory Object Fields

Field	Type	Description
id	string	Unique memory identifier
memoryType	string	One of: fact, preference, relationship, event, emotional_state, correction, character_self, spatial_change
content	string	The memory content text
confidence	number	Confidence score (0.0-1.0)
status	string	"active", "superseded", or "decayed"
source	string	Origin of the memory (e.g., "text_chat")
topic	string	Primary topic category
secondaryTopics	string[]	Additional related topics
sourceQuote	string	Original conversation text that produced this memory
accessCount	number	How many times this memory has been retrieved
createdAt	string	ISO 8601 creation timestamp
lastAccessedAt	string	ISO 8601 timestamp of last retrieval
extractedAt	string	ISO 8601 timestamp of extraction
updatedAt	string	ISO 8601 last update timestamp

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 fact memories, sorted by confidence
curl "https://api.estuary-ai.com/api/agents/{agent_id}/players/player_xyz/memories?memory_type=fact&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=event&limit=20`,
  { headers: { "X-API-Key": "est_your_api_key" } }
);
const data = await res.json();
console.log(`${data.total} event 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.

Response

{
  "totalActive": 87,
  "totalSuperseded": 5,
  "totalDecayed": 3,
  "byType": {
    "fact": 32,
    "preference": 15,
    "relationship": 8,
    "event": 18,
    "emotional_state": 6,
    "correction": 2,
    "character_self": 4,
    "spatial_change": 2
  },
  "coreFacts": 12
}

Field	Type	Description
totalActive	number	Active memories
totalSuperseded	number	Memories replaced by newer information
totalDecayed	number	Memories that have decayed below threshold
byType	object	Breakdown of active memories by type
coreFacts	number	Number of core facts

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": "fact" },
    { "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": "event",
        "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 (similarity + recency + confidence)
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"