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 turn is stored 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 write carries a deterministic idempotency seed.

Editor semantics

• add_items(items) — each MemoryItem.conversation is stored through MemorySync's extraction pipeline (facts, dedup, decay), scoped to that item's user_id. metadata keys ride along; metadata.ignore_roles filters roles out (e.g. ["assistant"] stores only user turns). Items whose extraction fails 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 this adapter's session rows for the user. 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 rows are always 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   # 26 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.