nat-memorysync

MemorySync memory backend for the NVIDIA NeMo Agent Toolkit (nvidia-nat).

Registers a memorysync_memory client that plugs into workflow YAML as a memory: section entry — usable from the toolkit's built-in add_memory / get_memory tools, from the automatic auto_memory_agent wrapper, and from any custom function that requests a memory client from the Builder.

pip install nat-memorysync

Requires Python 3.11+ (the toolkit's own floor). Installing this package pulls nvidia-nat-core; install nvidia-nat (or the plugin subpackages you need) for the full toolkit.

Why this instead of the in-repo editors?

The toolkit ships example editors for Mem0 and Zep. Both have sharp edges we designed against:

Wiring mode 1 — explicit memory tools

The agent decides when to store and when to recall:

memory:
  saas_memory:
    _type: memorysync_memory        # key comes from MEMORYSYNC_API_KEY env var

functions:
  add_memory:
    _type: add_memory
    memory: saas_memory
    description: Save any user preference or fact for later conversations.
  get_memory:
    _type: get_memory
    memory: saas_memory
    description: Recall previously saved user preferences and facts.

workflow:
  _type: react_agent
  tool_names: [add_memory, get_memory]
  llm_name: my_llm

Wiring mode 2 — automatic memory (auto_memory_agent)

No tools, no prompt changes — every user message is sent to fact extraction (assistant replies are not stored as memories) and every prompt is enriched automatically (requires nvidia-nat-langchain):

memory:
  saas_memory:
    _type: memorysync_memory

workflow:
  _type: auto_memory_agent
  augmented_fn: my_actual_workflow
  memory: saas_memory

search runs inside a hard 1.2 s budget here, so automatic memory can never stall a turn.

Builder API (Python)

from nat.builder.workflow_builder import WorkflowBuilder
from nat_memorysync import MemorySyncMemoryConfig

async with WorkflowBuilder() as builder:
    await builder.add_memory_client("saas_memory", MemorySyncMemoryConfig())
    editor = await builder.get_memory_client("saas_memory")

    from nat.memory.models import MemoryItem
    await editor.add_items([
        MemoryItem(
            conversation=[{"role": "user", "content": "I prefer teal dashboards"}],
            user_id="customer-1",
            metadata={"plan": "pro"},
        )
    ])
    items = await editor.search("dashboard preferences", top_k=5, user_id="customer-1")
    for it in items:
        print(it.similarity_score, it.memory)

Configuration

All fields are optional except the API key (env var or config field):

MemoryBaseConfig + RetryMixin knobs (num_retries, retry_on_status_codes, …) work too — retries are safe because every turn carries a deterministic idempotency seed: the server recognises a retried turn and extracts it once.

Editor semantics

• add_items(items) — the user turns of each MemoryItem.conversation are sent to MemorySync's fact extraction (facts, dedup, decay), scoped to that item's user_id; only the durable facts found are stored, never the turn text itself. Assistant replies are not stored as memories, so assistant (and system/tool) turns are not sent. Scalar metadata values ride along onto the facts; metadata.ignore_roles lists roles to skip and is never forwarded. An item with only memory set goes through the extraction path too, where the server decides what is durable. Items that fail to send are logged and skipped — a partial batch never raises mid-turn.
• search(query, top_k=..., user_id=...) — semantic recall, one MemoryItem per fact with similarity_score. user_id is required (loud ValueError, not a KeyError).
• remove_items(user_id=...) — deletes the user's memories labelled with this adapter's session (the facts extracted from the turns it sent carry the label). Add memory_id="..." for one row, or scope="user" to wipe the user's entire memory (explicit opt-in). No kwargs → ValueError.

Session scope comes from the toolkit's Context.get().conversation_id ContextVar when set (nat::<conversation_id>), else nat::default — but every write is additionally keyed by user_id, so an unset conversation id can never mix users.

Tests

pip install -e . nvidia-nat-core langchain-core pytest pytest-asyncio "httpx>=0.25,<1"
pytest tests -q   # 31 tests

The suite exercises the real WorkflowBuilder, NVIDIA's real add_memory/get_memory tool functions driving this editor end to end, plus named regression tests for every competitor bug in the table above.

License

MIT © MemorySync.