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

# Memory

## Overview

The `MemoryClient` is the Room API for room-scoped structured memory. Use it to build shared context that agents can ingest, query, and recall across workflows.

## CLI commands

Start with the CLI help, then use a few common commands:

```bash bash theme={null}
meshagent room memory --help
meshagent room memory list --room myroom
meshagent room memory create --room myroom --name customer-memory
meshagent room memory recall --room myroom --name customer-memory --query "latest priorities"
```

## Why use the Memory API?

* Preserve structured knowledge across tasks instead of reconstructing it from chat history each time.
* Ingest text, files, images, tables, and room storage content into a shared memory.
* Recall the most relevant entities and relationships when building prompts or workflows.

## How it works

A memory is a named dataset inside a room. You can create it, ingest data into it, inspect or query it directly, and use recall to retrieve relevant context. Some operations work at the entity and relationship level so you can maintain graph-like memory over time.

> Current implementation: MeshAgent room memory is currently backed by [Lance Graph](https://github.com/lance-format/lance-graph), which stores entities and relationships in a graph-oriented format. Lance Graph is a Cypher-capable graph query engine.

## Permissions and grants

The Memory API is controlled by the `memory` grant on the participant token.

In practice:

* `list` controls whether the participant can list memories
* memory entry grants can be scoped by `name` and `namespace`
* each entry can narrow permissions such as `create`, `drop`, `inspect`, `query`, `upsert`, `ingest`, `recall`, and `optimize`

See [API Scopes](../rest_api/api_scopes), [Participant Tokens](../rest_api/participant_tokens), and [Service YAML](../services/deployment/deploy_services).

## API reference

Use the methods below to create memories, ingest content, query or recall context, and maintain memory datasets over time.

### Python SDK signatures

The examples below show common workflows. The Python SDK exposes these parameters directly on `room.memory`:

```python Python theme={null}
await room.memory.list(namespace=None)
await room.memory.create(name="customer-memory", namespace=None, overwrite=False, ignore_exists=False)
await room.memory.drop(name="customer-memory", namespace=None, ignore_missing=False)
details = await room.memory.inspect(name="customer-memory", namespace=None)
rows = await room.memory.query(name="customer-memory", statement="MATCH (e) RETURN e LIMIT 10", namespace=None)

await room.memory.upsert_table(name="customer-memory", table="facts", records=records, merge=True, namespace=None)
await room.memory.upsert_nodes(name="customer-memory", records=nodes, merge=True, namespace=None)
await room.memory.upsert_relationships(name="customer-memory", records=relationships, merge=True, namespace=None)

result = await room.memory.ingest_text(
    name="customer-memory", text="ACME is planning a renewal review in Q3.",
    namespace=None, strategy="heuristic", llm_model=None, llm_temperature=None,
)
result = await room.memory.ingest_image(
    name="customer-memory", caption=None, data=None, mime_type=None, source=None,
    annotations=None, namespace=None, strategy="heuristic",
    llm_model=None, llm_temperature=None,
)
result = await room.memory.ingest_file(
    name="customer-memory", path=None, text=None, mime_type=None,
    namespace=None, strategy="heuristic", llm_model=None, llm_temperature=None,
)
result = await room.memory.ingest_from_table(
    name="customer-memory", table="customer_notes", text_columns=None,
    table_namespace=None, limit=None, namespace=None, strategy="heuristic",
    llm_model=None, llm_temperature=None,
)
result = await room.memory.ingest_from_storage(
    name="customer-memory", paths=["room://notes/acme.txt"],
    namespace=None, strategy="heuristic", llm_model=None, llm_temperature=None,
)

result = await room.memory.recall(
    name="customer-memory", query="renewal timeline", namespace=None,
    limit=5, include_relationships=True,
)
result = await room.memory.delete_entities(name="customer-memory", entity_ids=["acme"], namespace=None)
result = await room.memory.delete_relationships(name="customer-memory", relationships=relationships, namespace=None)
result = await room.memory.optimize(name="customer-memory", namespace=None, compact=True, cleanup=True)
```

### `list(namespace=None)`

* **Description**: List memory names in a namespace.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory list \
    --room myroom \
    --namespace team \
    --namespace support

  ```

  ```python Python theme={null}
  memories = await room.memory.list(namespace=["team", "support"])
  print(memories)

  ```

  ```dart Dart theme={null}
  final memories = await room.memory.list(namespace: ["team", "support"]);
  print(memories);

  ```
</CodeGroup>

### `create(name, ...)`

* **Description**: Create a memory.
* **Parameters**: `name`, optional `namespace`, `overwrite`, `ignore_exists`.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory create \
    --room myroom \
    --name customer-memory \
    --namespace team \
    --namespace support

  ```

  ```python Python theme={null}
  await room.memory.create(
    name="customer-memory",
    namespace=["team", "support"],
    overwrite=False,
  )

  ```

  ```dart Dart theme={null}
  await room.memory.create(
    name: "customer-memory",
    namespace: ["team", "support"],
    overwrite: false,
  );

  ```
</CodeGroup>

### `drop(name, ...)`

* **Description**: Delete a memory.
* **Parameters**: `name`, optional `namespace`, `ignore_missing`.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory drop \
    --room myroom \
    --name customer-memory \
    --namespace team \
    --namespace support \
    --ignore-missing

  ```

  ```python Python theme={null}
  await room.memory.drop(
    name="customer-memory",
    namespace=["team", "support"],
    ignore_missing=True,
  )

  ```

  ```dart Dart theme={null}
  await room.memory.drop(
    name: "customer-memory",
    namespace: ["team", "support"],
    ignoreMissing: true,
  );

  ```
</CodeGroup>

## More methods

These examples use the Python `MemoryClient` API. The CLI, Dart SDK, TypeScript SDK, and .NET SDK expose matching room-memory operations for the same methods.

### `inspect(name, ...)`

* **Description**: Return `MemoryDetails` including the memory path and dataset summaries.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory inspect \
    --room myroom \
    --name customer-memory

  ```

  ```python Python theme={null}
  details = await room.memory.inspect(name="customer-memory")
  print(details.path)
  for dataset in details.datasets:
    print(dataset.name, dataset.rows, dataset.columns)

  ```
</CodeGroup>

### `query(name, statement, ...)`

* **Description**: Run a graph query against a memory and return rows.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory query \
    --room myroom \
    --name customer-memory \
    --statement 'MATCH (e) RETURN e.name LIMIT 10'

  ```

  ```python Python theme={null}
  rows = await room.memory.query(
    name="customer-memory",
    statement="MATCH (e) RETURN e.name LIMIT 10",
  )
  print(rows)

  ```
</CodeGroup>

### `upsert_table(name, table, records, ...)`

* **Description**: Upsert arbitrary rows into a named memory dataset.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory upsert-table \
    --room myroom \
    --name customer-memory \
    --table facts \
    --records-json '[{"entity_id":"acme","summary":"Renewal expected in Q3"}]'

  ```

  ```python Python theme={null}
  await room.memory.upsert_table(
    name="customer-memory",
    table="facts",
    records=[
      {
        "entity_id": "acme",
        "summary": "Renewal expected in Q3",
      }
    ],
  )

  ```
</CodeGroup>

### `upsert_nodes(name, records, ...)`

* **Description**: Upsert entity nodes using `MemoryEntityRecord`.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory upsert-nodes \
    --room myroom \
    --name customer-memory \
    --records-json '[{"entity_id":"acme","name":"ACME","entity_type":"company","context":"Enterprise customer"}]'

  ```

  ```python Python theme={null}
  from meshagent.api.room_server_client import MemoryEntityRecord

  await room.memory.upsert_nodes(
    name="customer-memory",
    records=[
      MemoryEntityRecord(
        entity_id="acme",
        name="ACME",
        entity_type="company",
        context="Enterprise customer",
      )
    ],
  )

  ```
</CodeGroup>

### `upsert_relationships(name, records, ...)`

* **Description**: Upsert edges using `MemoryRelationshipRecord`.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory upsert-relationships \
    --room myroom \
    --name customer-memory \
    --records-json '[{"source_entity_id":"acme","target_entity_id":"renewal-q3","relationship_type":"HAS_MILESTONE","description":"Renewal target quarter"}]'

  ```

  ```python Python theme={null}
  from meshagent.api.room_server_client import MemoryRelationshipRecord

  await room.memory.upsert_relationships(
    name="customer-memory",
    records=[
      MemoryRelationshipRecord(
        source_entity_id="acme",
        target_entity_id="renewal-q3",
        relationship_type="HAS_MILESTONE",
        description="Renewal target quarter",
      )
    ],
  )

  ```
</CodeGroup>

### `ingest_text(name, text, ...)`

* **Description**: Extract memory from inline text.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory ingest-text \
    --room myroom \
    --name customer-memory \
    --text 'ACME is planning a renewal review in Q3.'

  ```

  ```python Python theme={null}
  result = await room.memory.ingest_text(
    name="customer-memory",
    text="ACME is planning a renewal review in Q3.",
  )
  print(result.stats.entities, result.stats.relationships)

  ```
</CodeGroup>

### `ingest_image(name, data, ...)`

* **Description**: Extract memory from an image and optional caption.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory ingest-image \
    --room myroom \
    --name customer-memory \
    --file ./whiteboard.png \
    --caption 'Customer planning whiteboard'

  ```

  ```python Python theme={null}
  with open("./whiteboard.png", "rb") as f:
    image_bytes = f.read()

  result = await room.memory.ingest_image(
    name="customer-memory",
    data=image_bytes,
    mime_type="image/png",
    caption="Customer planning whiteboard",
  )
  print(result.stats)

  ```
</CodeGroup>

### `ingest_file(name, path, ...)`

* **Description**: Extract memory from a file path visible to the room server, or from inline text.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory ingest-file \
    --room myroom \
    --name customer-memory \
    --path /data/acme-renewal.txt

  ```

  ```python Python theme={null}
  result = await room.memory.ingest_file(
    name="customer-memory",
    path="/data/acme-renewal.txt",
  )
  print(result.entity_ids)

  ```
</CodeGroup>

### `ingest_from_table(name, table, ...)`

* **Description**: Extract memory from room dataset rows.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory ingest-from-table \
    --room myroom \
    --name customer-memory \
    --table customer_notes \
    --text-column summary \
    --text-column notes \
    --limit 100

  ```

  ```python Python theme={null}
  result = await room.memory.ingest_from_table(
    name="customer-memory",
    table="customer_notes",
    text_columns=["summary", "notes"],
    limit=100,
  )
  print(result.stats)

  ```
</CodeGroup>

### `ingest_from_storage(name, paths, ...)`

* **Description**: Extract memory from one or more room storage paths.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory ingest-from-storage \
    --room myroom \
    --name customer-memory \
    --path room://notes/acme.txt \
    --path room://notes/renewal.txt

  ```

  ```python Python theme={null}
  result = await room.memory.ingest_from_storage(
    name="customer-memory",
    paths=["room://notes/acme.txt", "room://notes/renewal.txt"],
  )
  print(result.stats)

  ```
</CodeGroup>

### `recall(name, query, ...)`

* **Description**: Semantic recall using a natural-language query.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory recall \
    --room myroom \
    --name customer-memory \
    --query "What do we know about ACME's renewal timeline?" \
    --limit 5

  ```

  ```python Python theme={null}
  result = await room.memory.recall(
    name="customer-memory",
    query="What do we know about ACME's renewal timeline?",
    limit=5,
  )
  for item in result.items:
    print(item.entity_id, item.score)

  ```
</CodeGroup>

### `delete_entities(name, entity_ids, ...)`

* **Description**: Remove entities and their related edges.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory delete-entities \
    --room myroom \
    --name customer-memory \
    --entity-id acme

  ```

  ```python Python theme={null}
  result = await room.memory.delete_entities(
    name="customer-memory",
    entity_ids=["acme"],
  )
  print(result.deleted_entities, result.deleted_relationships)

  ```
</CodeGroup>

### `delete_relationships(name, relationships, ...)`

* **Description**: Remove relationships using `MemoryRelationshipSelector`.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory delete-relationships \
    --room myroom \
    --name customer-memory \
    --records-json '[{"source_entity_id":"acme","target_entity_id":"renewal-q3","relationship_type":"HAS_MILESTONE"}]'

  ```

  ```python Python theme={null}
  from meshagent.api.room_server_client import MemoryRelationshipSelector

  result = await room.memory.delete_relationships(
    name="customer-memory",
    relationships=[
      MemoryRelationshipSelector(
        source_entity_id="acme",
        target_entity_id="renewal-q3",
        relationship_type="HAS_MILESTONE",
      )
    ],
  )
  print(result.deleted_relationships)

  ```
</CodeGroup>

### `optimize(name, ...)`

* **Description**: Compact and clean up memory datasets.

<CodeGroup>
  ```bash CLI theme={null}
  meshagent room memory optimize \
    --room myroom \
    --name customer-memory \
    --compact \
    --cleanup

  ```

  ```python Python theme={null}
  result = await room.memory.optimize(
    name="customer-memory",
    compact=True,
    cleanup=True,
  )
  print(result)

  ```
</CodeGroup>

## Related guides

* [Room API Overview](./overview)
* [Datasets API](./datasets)
* [Storage API](./storage)