How to Add a Conversation Using the TencentDB Agent Memory Python SDK

Use the add_conversation method on the MemoryClient or AsyncMemoryClient class to submit message threads via a POST request to the /v3/conversation/add endpoint, while the SDK automatically injects tenant isolation parameters and resolves session contexts.

The TencentDB Agent Memory Python SDK manages conversational data through a strict-isolation architecture that prevents cross-tenant leakage. Adding a conversation requires instantiating a client with team, agent, user, and session identifiers, then passing a structured message list to the add_conversation method, which handles payload construction, null-value filtering, and transport.

Configure the Isolation Context

The SDK enforces data isolation through a four-tuple of identifiers supplied at client instantiation. When creating a MemoryClient, you must provide team_id, agent_id, user_id, and optionally session_id. These values are stored in an internal _IsolationCtx object defined in tencentdb_agent_memory/v3/client.py (lines 9-23).

The isolation context automatically merges these identifiers into every request body via self._iso.base_body(). If you need to override isolation parameters for a specific call without mutating the original client, the SDK provides a with_isolation clone method that returns a new client instance with modified context.

Invoke the add_conversation Method

To persist a conversation turn, call add_conversation on your client instance. The method signature accepts a messages parameter containing a list of dictionaries, where each dictionary specifies a role (e.g., "user", "assistant") and content string.

The implementation in tencentdb_agent_memory/v3/client.py (lines 30-41) enforces a critical server constraint: conversation writes require a non-empty session_id. The SDK invokes self._iso.resolve_session_for_write(session_id) to inject the client-level session ID if the call does not explicitly provide one, ensuring the server receives a valid isolation scope.

# pip install tencentdb-agent-memory

from tencentdb_agent_memory import MemoryClient

client = MemoryClient(
    team_id="team-123",
    agent_id="agent-abc",
    user_id="user-xyz",
    session_id="session-001"
)

response = client.add_conversation(
    messages=[
        {"role": "user", "content": "Hello, how's the weather?"},
        {"role": "assistant", "content": "It's sunny in Beijing today."}
    ]
)

print("Add-conversation response:", response)

Override Session Context for Specific Calls

While the client stores a default session_id, you can override it per-call by passing the session_id parameter directly to add_conversation. This temporarily bypasses the client-level default without modifying the underlying _IsolationCtx.

response = client.add_conversation(
    messages=[{"role": "user", "content": "What is the stock price?"}],
    session_id="session-002"  # Optional override for this request only

)

Request Construction and Transport Layer

Before transmission, the method constructs a JSON payload combining isolation fields, the resolved session ID, and the messages array. The SDK filters out null values using _strip_none to ensure clean request bodies (see v3/client.py lines 30-43).

The actual HTTP POST to {_V3}/conversation/add is executed by self._stub.post, defined in the low-level transport layer (tencentdb_agent_memory/_http.py). This stub handles authentication headers, retry logic, and JSON serialization.

Asynchronous Conversation Writes

For async workflows, use AsyncMemoryClient, which mirrors the synchronous API. The async variant awaits the same stub call, maintaining identical isolation semantics and payload construction.

import asyncio
from tencentdb_agent_memory import AsyncMemoryClient

async def add_conversation_async():
    async_client = AsyncMemoryClient(
        team_id="team-123",
        agent_id="agent-abc",
        user_id="user-xyz",
        session_id="session-003"
    )
    resp = await async_client.add_conversation(
        messages=[{"role": "user", "content": "Async demo"}]
    )
    print(resp)

asyncio.run(add_conversation_async())

Summary

• Strict isolation: Every MemoryClient requires team_id, agent_id, user_id, and session_id to prevent cross-tenant data leakage.
• Session resolution: The SDK automatically validates or injects session_id via _iso.resolve_session_for_write() before transmitting to POST /v3/conversation/add.
• Payload construction: The add_conversation method merges isolation context, resolved session IDs, and message lists, filtering nulls with _strip_none.
• Dual interface: Both synchronous (MemoryClient) and asynchronous (AsyncMemoryClient) implementations use the same transport stub and isolation logic defined in v3/client.py.

Frequently Asked Questions

What parameters are required to add a conversation using the Python SDK?

You must instantiate the client with team_id, agent_id, and user_id. The session_id can be set at the client level or passed per-call to add_conversation, but the server requires a non-empty value. The messages parameter must contain a list of dictionaries with role and content keys.

Can I override the session ID for a single add_conversation call?

Yes. Pass the session_id argument directly to the add_conversation method. The SDK uses resolve_session_for_write() to prioritize the call-level parameter over the client-level default stored in _IsolationCtx, allowing temporary context switching without cloning the client.

How does the SDK handle asynchronous conversation writes?

The AsyncMemoryClient class provides an add_conversation coroutine that awaits the same HTTP stub used by the synchronous client. It maintains identical isolation semantics and payload construction, differing only in its async/await interface.

Where does the SDK implement the conversation addition logic?

The primary implementation resides in tencentdb_agent_memory/v3/client.py (lines 30-43), which handles session resolution, payload assembly, and the _strip_none filter. The HTTP transport layer is implemented in tencentdb_agent_memory/_http.py, which executes the POST request to the /v3/conversation/add endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}