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

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, 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, Participant Tokens, and Service YAML.

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

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.

meshagent room memory list \
  --room myroom \
  --namespace team \
  --namespace support

memories = await room.memory.list(namespace=["team", "support"])
print(memories)

final memories = await room.memory.list(namespace: ["team", "support"]);
print(memories);

`create(name, ...)`

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

meshagent room memory create \
  --room myroom \
  --name customer-memory \
  --namespace team \
  --namespace support

await room.memory.create(
  name="customer-memory",
  namespace=["team", "support"],
  overwrite=False,
)

await room.memory.create(
  name: "customer-memory",
  namespace: ["team", "support"],
  overwrite: false,
);

`drop(name, ...)`

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

meshagent room memory drop \
  --room myroom \
  --name customer-memory \
  --namespace team \
  --namespace support \
  --ignore-missing

await room.memory.drop(
  name="customer-memory",
  namespace=["team", "support"],
  ignore_missing=True,
)

await room.memory.drop(
  name: "customer-memory",
  namespace: ["team", "support"],
  ignoreMissing: true,
);

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.

meshagent room memory inspect \
  --room myroom \
  --name customer-memory

details = await room.memory.inspect(name="customer-memory")
print(details.path)
for dataset in details.datasets:
  print(dataset.name, dataset.rows, dataset.columns)

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

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

meshagent room memory query \
  --room myroom \
  --name customer-memory \
  --statement 'MATCH (e) RETURN e.name LIMIT 10'

rows = await room.memory.query(
  name="customer-memory",
  statement="MATCH (e) RETURN e.name LIMIT 10",
)
print(rows)

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

Description: Upsert arbitrary rows into a named memory dataset.

meshagent room memory upsert-table \
  --room myroom \
  --name customer-memory \
  --table facts \
  --records-json '[{"entity_id":"acme","summary":"Renewal expected in Q3"}]'

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

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

Description: Upsert entity nodes using MemoryEntityRecord.

meshagent room memory upsert-nodes \
  --room myroom \
  --name customer-memory \
  --records-json '[{"entity_id":"acme","name":"ACME","entity_type":"company","context":"Enterprise customer"}]'

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",
    )
  ],
)

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

Description: Upsert edges using MemoryRelationshipRecord.

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"}]'

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",
    )
  ],
)

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

Description: Extract memory from inline text.

meshagent room memory ingest-text \
  --room myroom \
  --name customer-memory \
  --text 'ACME is planning a renewal review in Q3.'

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)

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

Description: Extract memory from an image and optional caption.

meshagent room memory ingest-image \
  --room myroom \
  --name customer-memory \
  --file ./whiteboard.png \
  --caption 'Customer planning whiteboard'

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)

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

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

meshagent room memory ingest-file \
  --room myroom \
  --name customer-memory \
  --path /data/acme-renewal.txt

result = await room.memory.ingest_file(
  name="customer-memory",
  path="/data/acme-renewal.txt",
)
print(result.entity_ids)

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

Description: Extract memory from room dataset rows.

meshagent room memory ingest-from-table \
  --room myroom \
  --name customer-memory \
  --table customer_notes \
  --text-column summary \
  --text-column notes \
  --limit 100

result = await room.memory.ingest_from_table(
  name="customer-memory",
  table="customer_notes",
  text_columns=["summary", "notes"],
  limit=100,
)
print(result.stats)

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

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

meshagent room memory ingest-from-storage \
  --room myroom \
  --name customer-memory \
  --path room://notes/acme.txt \
  --path room://notes/renewal.txt

result = await room.memory.ingest_from_storage(
  name="customer-memory",
  paths=["room://notes/acme.txt", "room://notes/renewal.txt"],
)
print(result.stats)

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

Description: Semantic recall using a natural-language query.

meshagent room memory recall \
  --room myroom \
  --name customer-memory \
  --query "What do we know about ACME's renewal timeline?" \
  --limit 5

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)

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

Description: Remove entities and their related edges.

meshagent room memory delete-entities \
  --room myroom \
  --name customer-memory \
  --entity-id acme

result = await room.memory.delete_entities(
  name="customer-memory",
  entity_ids=["acme"],
)
print(result.deleted_entities, result.deleted_relationships)

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

Description: Remove relationships using MemoryRelationshipSelector.

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"}]'

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)

`optimize(name, ...)`

Description: Compact and clean up memory datasets.

meshagent room memory optimize \
  --room myroom \
  --name customer-memory \
  --compact \
  --cleanup

result = await room.memory.optimize(
  name="customer-memory",
  compact=True,
  cleanup=True,
)
print(result)

Introduction

Rooms

Agents & Tools

Deploy & Manage

Projects

Product Interfaces

Developer Reference

Overview

CLI commands

Why use the Memory API?

How it works

Permissions and grants

API reference

Python SDK signatures

`list(namespace=None)`

`create(name, ...)`

`drop(name, ...)`

More methods

`inspect(name, ...)`

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

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

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

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

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

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

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

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

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

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

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

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

`optimize(name, ...)`

​Overview

​CLI commands

​Why use the Memory API?

​How it works

​Permissions and grants

​API reference

​Python SDK signatures

​list(namespace=None)

​create(name, ...)

​drop(name, ...)

​More methods

​inspect(name, ...)

​query(name, statement, ...)

​upsert_table(name, table, records, ...)

​upsert_nodes(name, records, ...)

​upsert_relationships(name, records, ...)

​ingest_text(name, text, ...)

​ingest_image(name, data, ...)

​ingest_file(name, path, ...)

​ingest_from_table(name, table, ...)

​ingest_from_storage(name, paths, ...)

​recall(name, query, ...)

​delete_entities(name, entity_ids, ...)

​delete_relationships(name, relationships, ...)

​optimize(name, ...)

​Related guides

Overview

CLI commands

Why use the Memory API?

How it works

Permissions and grants

API reference

Python SDK signatures

`list(namespace=None)`

`create(name, ...)`

`drop(name, ...)`

More methods

`inspect(name, ...)`

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

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

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

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

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

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

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

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

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

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

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

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

`optimize(name, ...)`

Related guides