Memory API

Base path: /api/memory

All endpoints require authentication. See API Overview for auth details.

Tip

For memory management, use the Memory page in the Snippbot UI.

Endpoints

Method	Path	Description
GET	/api/memory/episodes	List episodes
GET	/api/memory/episodes/{id}	Get an episode
POST	/api/memory/episodes	Create an episode (inject memory)
DELETE	/api/memory/episodes/{id}	Delete a single episode
GET	/api/memory/episodes/{id}/related	Get related episodes
GET	/api/memory/search	Full-text and semantic search
GET	/api/memory/clusters	Get memory clusters
GET	/api/memory/graph	Get the knowledge graph
GET	/api/memory/stats	Get memory statistics
POST	/api/memory/consolidate/conversations	Consolidate memory from conversations
POST	/api/memory/generate-episodes	Generate episodes from conversations
POST	/api/memory/backfill-entities	Backfill entity data for episodes
GET	/api/settings/memory	Get memory settings
PUT	/api/settings/memory	Update memory settings
GET	/api/settings/memory/export	Export memory data as JSON
DELETE	/api/settings/memory/data	Clear all memory data

Episodes

List episodes

GET /api/memory/episodes

Query parameters:

Parameter	Description
limit	Max results (default: 20, max: 100)
offset	Pagination offset (default: 0)
cluster_id	Filter by cluster ID
agent_id	Filter by agent ID

Response:

{
  "episodes": [
    {
      "id": "ep_abc123",
      "content": "User asked about FastAPI dependency injection...",
      "summary": null,
      "source": "conversation",
      "valence": 0.24,
      "importance": 0.6,
      "access_count": 3,
      "created_at": "2026-03-02T14:00:00Z",
      "updated_at": "2026-03-02T14:00:00Z"
    }
  ],
  "total": 1247,
  "limit": 20,
  "offset": 0
}

Get an episode

GET /api/memory/episodes/{id}

Create an episode (inject memory)

POST /api/memory/episodes

{
  "content": "Note: always use the snippbot_ prefix for database tables",
  "importance": 0.7,
  "valence": 0.0,
  "topics": ["conventions"],
  "agent_id": "agent_abc123"
}

Only content is required. All other fields are optional.

Use this to inject persistent instructions or context into an agent’s memory.

Delete an episode

DELETE /api/memory/episodes/{id}

Deletes a single episode by ID.

Caution

There is no bulk delete endpoint. Episodes must be deleted individually.

Related episodes

GET /api/memory/episodes/{id}/related

Returns episodes related to the given episode.

Search

Full-text and semantic search

GET /api/memory/search?q=database+migration+strategy&mode=hybrid&limit=10

Searches across all episodes using the selected mode. Pass natural language queries to find conceptually related memories.

Query parameters:

Parameter	Description
q	Search query string (required)
mode	Search mode: hybrid (default), keyword, or semantic
limit	Max results (default: 10, max: 100)
offset	Pagination offset (default: 0)
start_date	ISO 8601 date filter (since)
end_date	ISO 8601 date filter (until)
source	Filter by episode source (e.g., conversation, task, insight)

Response:

{
  "query": "database migration strategy",
  "mode": "hybrid",
  "limit": 10,
  "offset": 0,
  "results": [
    {
      "episode": {
        "id": "ep_abc123",
        "content": "User asked about database migration strategy...",
        "summary": null,
        "valence": 0.0,
        "importance": 0.6,
        "topics": [],
        "entities": [
          { "id": "ent_xyz", "name": "Sql", "type": "concept", "mentions": 2 }
        ],
        "source": "conversation",
        "created_at": "2026-03-01T10:00:00Z"
      },
      "score": 0.92,
      "source": "conversation",
      "highlights": ["...we decided on a **database migration strategy** that..."]
    }
  ],
  "total": 3
}

Note

Search results use score (not relevance) and highlights (an array, not a single string). Each result nests the episode data inside a results[].episode object.

Clusters

GET /api/memory/clusters

Returns memory clusters — groups of related episodes identified by the memory system.

Query parameters:

Parameter	Description
n	Number of clusters to compute (default: 4, range: 2-8)
agent_id	Filter clusters for a specific agent

Knowledge graph

Get the graph

GET /api/memory/graph

Returns the full knowledge graph (entities and relationships).

Note

Only GET /api/memory/graph exists. There are no separate endpoints for adding nodes, adding edges, or querying by entity/relation. The graph is built automatically as the agent processes conversations.

Memory maintenance

Consolidate from conversations

POST /api/memory/consolidate/conversations

Triggers memory consolidation from conversation history.

Generate episodes from conversations

POST /api/memory/generate-episodes

Generates episodic memory entries from existing conversation data.

Backfill entities

POST /api/memory/backfill-entities

Backfills entity extraction for episodes that were created before entity extraction was enabled.

Memory settings

Memory settings are managed under the Settings API, not under /api/memory:

Get memory settings

GET /api/settings/memory

Update memory settings

PUT /api/settings/memory

Export memory data

GET /api/settings/memory/export

Returns a JSON file containing all episodes and metadata as a download.

Clear all memory data

DELETE /api/settings/memory/data

Deletes all episodes, the vector index, and the knowledge graph. This action is irreversible.

Response:

{
  "cleared": 4821
}

Memory stats

GET /api/memory/stats

{
  "total_episodes": 4821,
  "total_entities": 142,
  "total_relations": 389,
  "avg_importance": 0.54,
  "avg_valence": 0.12,
  "importance_distribution": [12, 45, 89, 210, 380, 920, 1100, 800, 180, 85],
  "source_distribution": { "conversation": 4200, "task": 400, "insight": 221 },
  "entity_type_distribution": { "language": 12, "framework": 18, "tool": 30, "concept": 82 },
  "recall_feedback": { "total_recalls": 320, "used_count": 210, "ignored_count": 110, "usage_rate": 0.66 }
}