Memory and tool patterns

TAC provides multiple ways to retrieve memory and define tools. This guide explains when to use each pattern and the tradeoffs involved.

Memory retrieval patterns

TAC offers three ways to retrieve memory context for your agent. Choose the pattern that best fits your use case.

Pattern 1: Auto-retrieval (recommended for most cases)

Enable automatic memory retrieval in your channel configuration. TAC fetches memory before calling your on_message_ready callback.

PythonTypeScript

1from tac.channels.sms import SMSChannel, SMSChannelConfig
2from tac.channels.voice import VoiceChannel, VoiceChannelConfig
3
4sms_channel = SMSChannel(
5    tac,
6    config=SMSChannelConfig(auto_retrieve_memory=True),
7)
8
9voice_channel = VoiceChannel(
10    tac,
11    config=VoiceChannelConfig(auto_retrieve_memory=True),
12)
13
14async def handle_message_ready(
15    message: str,
16    context: ConversationSession,
17    memory: TACMemoryResponse | None,
18) -> str | None:
19    # Memory is already fetched and passed to your callback
20    if memory:
21        observations = memory.observations
22        profile = context.profile

When to use:

Most production agents
When you need memory for every message
When you want TAC to handle memory retrieval timing

Performance: One memory API call per message. TAC fetches memory in parallel with other operations.

Pattern 2: Manual retrieval (conditional fetching)

Retrieve memory on demand within your callback when you need conditional logic or custom queries.

PythonTypeScript

1from tac.channels.sms import SMSChannel, SMSChannelConfig
2
3sms_channel = SMSChannel(
4    tac,
5    config=SMSChannelConfig(auto_retrieve_memory=False),  # Disabled
6)
7
8async def handle_message_ready(
9    message: str,
10    context: ConversationSession,
11    memory: TACMemoryResponse | None,  # Will be None
12) -> str | None:
13    # Conditionally retrieve memory
14    if needs_personalization(message):
15        memory = await tac.retrieve_memory(context, query="customer preferences")
16    
17    # Or retrieve with a specific query
18    if "order" in message.lower():
19        memory = await tac.retrieve_memory(context, query="order history")

When to use:

Memory only needed for certain message types
Custom semantic queries based on message content
Cost optimization (fewer memory API calls)
Debugging or testing without memory

Performance: You control when memory API calls happen. Can reduce costs by skipping memory for simple queries.

Pattern 3: OpenAI adapter (Python only)

Use the OpenAI adapter to inject memory automatically into OpenAI API calls without manual prompt building.

1from openai import AsyncOpenAI
2from tac.adapters.openai import with_tac_memory
3
4openai_client = AsyncOpenAI()
5
6async def handle_message_ready(
7    message: str,
8    context: ConversationSession,
9    memory: TACMemoryResponse | None,
10) -> str | None:
11    # Wrap client with memory - TAC injects memory into system prompt
12    client = with_tac_memory(openai_client, memory, context)
13
14    # Memory is automatically injected as system message or instructions
15    response = await client.chat.completions.create(
16        model="gpt-4o-mini",
17        messages=conversation_history[context.conversation_id],
18    )
19
20    # Or with Responses API
21    response = await client.responses.create(
22        model="gpt-5.4-mini",
23        instructions="You are a helpful agent.",
24        input=conversation_history[context.conversation_id],
25    )

When to use:

OpenAI-specific projects (Chat Completions or Responses API)
Want automatic memory formatting
Don't need custom memory prompt structure

Performance: Same as auto-retrieval (memory fetched once per message), but saves you from manual prompt building.

Pattern comparison

Pattern	Setup Complexity	Control	Performance	Best For
Auto-retrieval	Low	Medium	Good	Most agents
Manual retrieval	Medium	High	Best (optimizable)	Conditional memory, custom queries
OpenAI adapter	Low	Low	Good	OpenAI projects

Tool patterns

For custom tools (API calls, database queries, business logic), use your LLM framework's native tool definitions. TAC is framework-agnostic and works with any tool format your LLM supports.

TAC provides built-in tools for common agent operations like knowledge search, memory retrieval, and escalation to human agents.

PythonTypeScript

1from tac.tools import (
2    create_knowledge_tool,
3    create_memory_tool,
4    create_studio_handoff_tool,
5)
6
7# Knowledge base search
8knowledge_tool = create_knowledge_tool(
9    tac=tac,
10    knowledge_base_id="know_knowledgebase_xxxxx",
11    name="search_docs",
12    description="Search product documentation",
13)
14
15# Memory recall with custom query
16memory_tool = create_memory_tool(
17    tac=tac,
18    name="recall_history",
19    description="Recall past interactions with customer",
20)
21
22# Studio Flow handoff (human escalation)
23handoff_tool = create_studio_handoff_tool(
24    tac=tac,
25    flow_sid="FWxxxxx",
26    name="escalate_to_human",
27    description="Transfer to human agent",
28)
29
30tac.register_tool(knowledge_tool)
31tac.register_tool(memory_tool)
32tac.register_tool(handoff_tool)

When to use:

Knowledge search across your Enterprise Knowledge bases
Memory recall for past customer interactions
Escalation to human agents via Studio Flows

Performance considerations

Memory retrieval

Auto-retrieval: Fetches memory in parallel with other TAC operations. Minimal latency impact.
Manual retrieval: Only fetches when called. Can reduce costs by skipping memory for simple queries.
OpenAI adapter: Same performance as auto-retrieval, but formats memory automatically.

Tool execution

Built-in tools: Include Twilio API call latency for knowledge search, memory recall, and escalation operations.

Best practices

Start with auto-retrieval: Use auto-retrieval unless you have a specific reason not to. It's simple and performant.
Use manual retrieval for optimization: If memory is only needed for 20% of messages, manual retrieval can save 80% of memory API calls.
Prefer built-in tools: Use TAC's built-in tools (knowledge, memory, handoff) when possible. They handle Twilio API integration correctly.
Keep tools focused: Each tool should do one thing well. Don't create mega-tools that handle multiple operations.
Document tool parameters: LLMs rely on your tool descriptions. Be specific about what each parameter does and when to use the tool.

Next steps

Channels: Learn about channel configuration and transport mechanisms.
Core concepts: Understand TAC's architecture and component relationships.