purra-mem0 · Python

English | 简体中文

Scoped memory, retrieval, and lifecycle management using the synchronous Mem0 OSS Memory client. Requires Python 3.11+. SDK calls run in a worker thread.

Install

From the repository root:

python -m pip install . ./integrations/mem0/python

Managed callbacks use the native PurrA adapters included in this package; no LangChain installation is required.

Before importing Mem0, set MEM0_TELEMETRY=false and an application-owned MEM0_DIR. Explicitly configure the LLM, embedder, vector_store, and history_db_path. Hosted MemoryClient and AsyncMemory are not supported.

Save and read

The application supplies mem0_config, authenticated user_id, authorized project_id, and a persistent journal_path:

from mem0 import Memory
from purra_mem0 import Mem0Memory, MemoryScope, MemorySource

sdk = Memory.from_config(mem0_config)
memory = Mem0Memory(
    client=sdk,
    scope=MemoryScope(user=user_id, project=project_id),
    journal_path=journal_path,
)

async def save_preference():
    saved = await memory.add(
        "Reply in Chinese.",
        source=MemorySource("preference:language", "1"),
        key="preference:language:1",
    )
    return await memory.get(saved.ids[0])

add creates an active record by default; use state="pending" for review first. get returns None for unavailable records. Updates, state changes, and deletions require the current version and a stable operation key.

Connect to an Agent

from purra.retrieval import RetrieverTool
from purra_mem0 import MemoryContext

recall = RetrieverTool(
    retriever=memory,
    name="recallMemory",
    description="Recall saved preferences and facts.",
)
context = MemoryContext(
    memory=memory,
    query=lambda request: request.latest_user_text(),
)

Register recall.registration in the Agent's tool catalog, or compose context with its context providers. The memory instance already binds the scope. For explicit record selection, use assemble_memory_context(memory, ids, allowance).

Managed model calls

Use the following configuration instead of a raw SDK client when calls need persistent budgets. Storage paths, embedding dimensions, and the budget key come from the application; the numeric limits below illustrate a budget configuration.

model_tasks is the runner supplied by a PurrA extension factory, and model_request selects its model. The async embed(texts, signal) callback must return EmbeddingResult with vectors and any reported input-token usage.

from purra_mem0 import (
    MemoryBudget, MemoryProviders, create_managed_client, run_model,
)

client = create_managed_client(
    embedding_dims=embedding_dimensions,
    config={"vector_store": vector_store_config, "history_db_path": history_path},
)
providers = MemoryProviders(
    budget=MemoryBudget(
        key=budget_key,
        max_llm_calls=4,
        max_embedding_calls=64,
        max_input_chars=100_000,
        max_output_tokens=8192,
        result_capacity_target_tokens=2048,
    ),
    complete=run_model(model_tasks, model_request),
    embed=embed,
)
memory = Mem0Memory(
    client=client,
    providers=providers,
    scope=MemoryScope(user=user_id, project=project_id),
    journal_path=journal_path,
    allow_inference=True,
)

Use memory.budget_usage() to inspect admitted and reported usage. Raw SDK mode reports internal usage as unknown.

Extract and review

With managed providers and allow_inference=True:

from purra_mem0 import MemoryWorkflow

workflow = MemoryWorkflow(memory)

async def capture(messages, source, operation_key):
    return await workflow.capture(messages, source=source, key=operation_key)

This configuration reviews candidates and leaves them pending. To apply decisions, pass an async policy(candidate, review) and a stable policy_revision to MemoryWorkflow. Return an authorized MemoryResolution that retains the review key, or None to leave the candidate pending.

Lifecycle

Before shutdown, call await memory.drain() and memory.close(), then close SDK and provider resources. For paging, withdrawal, evidence validation, and uncertain writes, see the memory lifecycle guide.

Native managed providers

create_managed_client inject native LLM and Embedding adapters into a version-pinned, package-private Mem0 module. Calls retain the existing PurrA budget, cancellation and result validation. Explicit vector dimensions must agree; the managed path rejects LangChain vector stores. It neither patches the installed SDK nor starts a proxy server. See third-party notices. Raw SDK clients remain host-owned and do not acquire managed accounting automatically.