title	Memories API
description	Reference for Episodic memory ingestion and retrieval
icon	brain

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.