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.

​
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

If a deployed service needs to use room memory, its participant token needs the appropriate Room API grants. See API Scopes and Packaging and Deploying Services.

​
CLI and SDK availability

  • CLI: full room-memory command set (list, create, drop, inspect, query, recall, ingest, optimize, and more).
  • Python: full MemoryClient API.
  • Dart: list, create, and drop helpers.
  • TypeScript/.NET: use the CLI or the generic invoke API (room.invoke(...) / room.Invoke(...)) for memory operations.

​
Core API Methods

​
list

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

​
create

  • 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

  • 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

​
Advanced Methods

These examples use the full Python MemoryClient API. The CLI exposes matching room-memory commands for the same operations.

​
inspect

  • Description: Return MemoryDetails including the memory path and dataset summaries.
meshagent room memory inspect \
  --room myroom \
  --name customer-memory

​
query

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • Description: Remove entities and their related edges.
meshagent room memory delete-entities \
  --room myroom \
  --name customer-memory \
  --entity-id acme

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

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