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={"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 | Key-value filters to apply to the search (metadata matching). |
timeout | int | None | Request timeout in seconds. Uses client default if omitted. |
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
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.
