Skip to main content

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

​
list(namespace=None)

  • Description: List memory names in a namespace.
meshagent room memory list \
  --room myroom \
  --namespace team \
  --namespace support

​
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

​
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

​
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

​
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'

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

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

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

​
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.'

​
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'

​
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

​
ingest_from_table(name, table, ...)

  • Description: Extract memory from room database rows.
meshagent room memory ingest-from-table \
  --room myroom \
  --name customer-memory \
  --table customer_notes \
  --text-column summary \
  --text-column notes \
  --limit 100

​
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

​
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

​
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

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

​
optimize(name, ...)

  • Description: Compact and clean up memory datasets.
meshagent room memory optimize \
  --room myroom \
  --name customer-memory \
  --compact \
  --cleanup