> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.getzep.com/_mcp/server.

# Performance Optimization Guide

> Best practices for optimizing Zep performance in production

This guide covers best practices for optimizing Zep's performance in production environments.

## Reuse the Zep SDK Client

The Zep SDK client maintains an HTTP connection pool that enables connection reuse, significantly reducing latency by avoiding the overhead of establishing new connections. To optimize performance:

* Create a single client instance and reuse it across your application
* Avoid creating new client instances for each request or function
* Consider implementing a client singleton pattern in your application
* For serverless environments, initialize the client outside the handler function

## Optimizing Memory Operations

The `memory.add` and `memory.get` methods are optimized for conversational messages and low-latency retrieval. For optimal performance:

* Keep individual messages under 10K characters
* Use `graph.add` for larger documents, tool outputs, or business data
* Consider chunking large documents before adding them to the graph (the `graph.add` endpoint has a 10,000 character limit)
* Remove unnecessary metadata or content before persistence
* For bulk document ingestion, process documents in parallel while respecting rate limits

```python
# Recommended for conversations
zep_client.memory.add(
    session_id="session_123",
    message={
        "role": "human",
        "content": "What's the weather like today?"
    }
)

# Recommended for large documents
await zep_client.graph.add(
    data=document_content,  # Your chunked document content
    user_id=user_id,       # Or group_id for group graphs
    type="text"            # Can be "text", "message", or "json"
)
```

### Get the memory context string sooner

Additionally, you can request the memory context directly in the response to the `memory.add()` call.
This optimization eliminates the need for a separate `memory.get()` if you happen to only need the context.
Read more about [Memory Context](/concepts/#memory-context).

In this scenario you can pass in the `return_context=True` flag to the `memory.add()` method.
Zep will perform a user graph search right after persisting the memory and return the context relevant to the recently added memory.

**`Python`**

```python Python
memory_response = await zep_client.memory.add(
    session_id=session_id,
    messages=messages,
    return_context=True
)

context = memory_response.context
```

**`TypeScript`**

```typescript TypeScript
const memoryResponse = await zepClient.memory.add(sessionId, {
    messages: messages,
    returnContext: true
});

const context = memoryResponse.context;
```

**`Go`**

```go Go
memoryResponse, err := zepClient.Memory.Add(
    context.TODO(),
    sessionID,
    &zep.AddMemoryRequest{
        Messages: messages,
        ReturnContext: zep.Bool(true),
    },
)
if err != nil {
    // handle error
}
memoryContext := memoryResponse.Context
```

> **Tip**
>
> Read more in the [Memory SDK Reference](/sdk-reference/memory#add)

## Optimizing Search Queries

Zep uses hybrid search combining semantic similarity and BM25 full-text search. For optimal performance:

* Keep your queries concise. Queries are automatically truncated to 8,192 tokens (approximately 32,000 Latin characters)
* Longer queries may not improve search quality and will increase latency
* Consider breaking down complex searches into smaller, focused queries
* Use specific, contextual queries rather than generic ones

Best practices for search:

* Keep search queries concise and specific
* Structure queries to target relevant information
* Use natural language queries for better semantic matching
* Consider the scope of your search (user vs group graphs)

```python
# Recommended - concise query
results = await zep_client.graph.search(
    user_id=user_id,  # Or group_id for group graphs
    query="project requirements discussion"
)

# Not recommended - overly long query
results = await zep_client.graph.search(
    user_id=user_id,
    query="very long text with multiple paragraphs..."  # Will be truncated
)
```

## Summary

* Reuse Zep SDK client instances to optimize connection management
* Use appropriate methods for different types of content (`memory.add` for conversations, `graph.add` for large documents)
* Keep search queries focused and under the token limit for optimal performance