> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memmachine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memories API

> Reference for Episodic memory ingestion and retrieval

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.

```python theme={null}
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.

```python theme={null}
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. |

<Note>
  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.
</Note>

***

## 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.

```python theme={null}
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. |

***

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.