Memories API

The client.memories namespace provides methods for storing and searching “Episodic” memories—the raw stream of interactions and events associated with a project.

Ingestion

`add`

Adds a new interaction or observation to the episodic memory store.

client.memories.add(
    org_id="my_org",
    project_id="my_proj",
    content="The user prefers Python over JavaScript.",
    role="user",
    metadata={"source": "chat_v3"}
)

Parameter	Type	Default	Description
`org_id`	`str`	Required	Organization identifier.
`project_id`	`str`	Required	Project identifier.
`content`	`str`	Required	The actual text of the memory episode.
`role`	`str`	`"user"`	The role of the speaker (e.g., `"user"`, `"assistant"`, `"system"`).
`producer`	`str`	`None`	Identifier of the entity that produced the message.
`produced_for`	`str`	`None`	Identifier of the entity the message was intended for.
`timestamp`	`str`	`None`	ISO-8601 timestamp string. Defaults to current server time.
`metadata`	`dict`	`None`	Arbitrary key-value pairs for filtering and categorization.

Retrieval & Search

`search`

Performs a hybrid semantic search across the episodic memory store to find relevant context.

results = client.memories.search(
    org_id="my_org",
    project_id="my_proj",
    query="What are the user's coding preferences?",
    limit=5,
    expand_context=2,
    score_threshold=0.65,
    agent_mode=True,
    filter_dict={"m.source": "chat_v3"},
)

Parameter	Type	Default	Description
`org_id`	`str`	Required	Organization identifier.
`project_id`	`str`	Required	Project identifier.
`query`	`str`	Required	The natural language search query.
`limit`	`int`	`10`	Maximum number of results to return.
`expand_context`	`int`	`0`	Number of neighboring episodic entries to include around each long-term match.
`score_threshold`	`float`	`None`	Minimum episodic retrieval score to keep. Not supported when `agent_mode=True`.
`agent_mode`	`bool`	`False`	Whether to use retrieval-agent search orchestration.
`filter_dict`	`dict`	`None`	Metadata filters to apply to the search. User metadata keys must be prefixed with `m.` / `metadata.` (for example `{"m.source": "chat_v3"}`). Unknown or misspelled fields return a 400 error.
`timeout`	`int`	`None`	Request timeout in seconds. Uses client default if omitted.

When constructing filters, always prefix user metadata fields with m. or metadata.. For example, use {"m.user_id": "123"} instead of {"user_id": "123"}. Filters that reference unqualified user metadata fields (or misspelled built-in fields) now fail fast with a 400 error instead of being ignored.

Management

`list_episodic`

Retrieves a paginated list of raw memory episodes.

Parameter	Type	Default	Description
`org_id`	`str`	Required	Organization identifier.
`project_id`	`str`	Required	Project identifier.
`limit`	`int`	`50`	Number of items per page.
`offset`	`int`	`0`	Number of items to skip.

`delete_all_episodic`

Permanently removes all episodic memories from a specific project.

client.memories.delete_all_episodic(org_id="my_org", project_id="my_proj")

Configuration

`configure_episodic_memory`

Adjusts the behavior of episodic memory for a project at runtime.

Parameter	Type	Default	Description
`enabled`	`bool`	`True`	Whether to allow episodic memory ingestion/retrieval.
`long_term_memory_enabled`	`bool`	`True`	Enable vector-based retrieval for older memories.
`short_term_memory_enabled`	`bool`	`True`	Enable retrieval of the most recent interactions.

Advanced semantic structures like Sets, Categories, and Tags have been moved to the client.semantic namespace to provide better structural clarity.

Introduction

MCP Tools

REST API

Typescript REST SDK

PythonSDK Client

Python SDK Server

Ingestion

`add`

Retrieval & Search

`search`

Management

`list_episodic`

`delete_all_episodic`

Configuration

`configure_episodic_memory`

​Ingestion

​add

​Retrieval & Search

​search

​Management

​list_episodic

​delete_all_episodic

​Configuration

​configure_episodic_memory

Ingestion

`add`

Retrieval & Search

`search`

Management

`list_episodic`

`delete_all_episodic`

Configuration

`configure_episodic_memory`