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