Python SDK

📢 Announcing our research paper: Zentry achieves 26% higher accuracy than OpenAI Memory, 91% lower latency, and 90% token savings! Read the paper to learn how we're revolutionizing AI agent memory.

Welcome to the zentry quickstart guide. This guide will help you get up and running with zentry in no time.

Installation

To install zentry, you can use pip. Run the following command in your terminal:

pip install zentryai

Basic Usage

Initialize zentry

Basic
Async
Advanced
Advanced (Graph Memory)

import os
from zentry import Memory

os.environ["OPENAI_API_KEY"] = "your-api-key"

m = Memory()

Store a Memory

messages = [
    {"role": "user", "content": "I'm planning to watch a movie tonight. Any recommendations?"},
    {"role": "assistant", "content": "How about a thriller movies? They can be quite engaging."},
    {"role": "user", "content": "I'm not a big fan of thriller movies but I love sci-fi movies."},
    {"role": "assistant", "content": "Got it! I'll avoid thriller recommendations and suggest sci-fi movies in the future."}
]

# Store inferred memories (default behavior)
result = m.add(messages, user_id="alice", metadata={"category": "movie_recommendations"})

# Store raw messages without inference
# result = m.add(messages, user_id="alice", metadata={"category": "movie_recommendations"}, infer=False)

Retrieve Memories

# Get all memories
all_memories = m.get_all(user_id="alice")

# Get a single memory by ID
specific_memory = m.get("892db2ae-06d9-49e5-8b3e-585ef9b85b8e")

Search Memories

related_memories = m.search(query="What do you know about me?", user_id="alice")

Update a Memory

result = m.update(memory_id="892db2ae-06d9-49e5-8b3e-585ef9b85b8e", data="I love India, it is my favorite country.")

Memory History

history = m.history(memory_id="892db2ae-06d9-49e5-8b3e-585ef9b85b8e")

Delete Memory

# Delete a memory by id
m.delete(memory_id="892db2ae-06d9-49e5-8b3e-585ef9b85b8e")
# Delete all memories for a user
m.delete_all(user_id="alice")

Reset Memory

m.reset() # Reset all memories

Configuration Parameters

zentry offers extensive configuration options to customize its behavior according to your needs. These configurations span across different components like vector stores, language models, embedders, and graph stores.

Vector Store Configuration

Parameter	Description	Default
`provider`	Vector store provider (e.g., “qdrant”)	“qdrant”
`host`	Host address	”localhost”
`port`	Port number	6333

LLM Configuration

Parameter	Description	Provider
`provider`	LLM provider (e.g., “openai”, “anthropic”)	All
`model`	Model to use	All
`temperature`	Temperature of the model	All
`api_key`	API key to use	All
`max_tokens`	Tokens to generate	All
`top_p`	Probability threshold for nucleus sampling	All
`top_k`	Number of highest probability tokens to keep	All
`http_client_proxies`	Allow proxy server settings	AzureOpenAI
`models`	List of models	Openrouter
`route`	Routing strategy	Openrouter
`openrouter_base_url`	Base URL for Openrouter API	Openrouter
`site_url`	Site URL	Openrouter
`app_name`	Application name	Openrouter
`ollama_base_url`	Base URL for Ollama API	Ollama
`openai_base_url`	Base URL for OpenAI API	OpenAI
`azure_kwargs`	Azure LLM args for initialization	AzureOpenAI
`deepseek_base_url`	Base URL for DeepSeek API	DeepSeek

Embedder Configuration

Parameter	Description	Default
`provider`	Embedding provider	”openai”
`model`	Embedding model to use	”text-embedding-3-small”
`api_key`	API key for embedding service	None

Graph Store Configuration

Parameter	Description	Default
`provider`	Graph store provider (e.g., “neo4j”)	“neo4j”
`url`	Connection URL	None
`username`	Authentication username	None
`password`	Authentication password	None

General Configuration

Parameter	Description	Default
`history_db_path`	Path to the history database	”/history.db”
`version`	API version	”v1.1”
`custom_fact_extraction_prompt`	Custom prompt for memory processing	None
`custom_update_memory_prompt`	Custom prompt for update memory	None

Complete Configuration Example

config = {
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "host": "localhost",
            "port": 6333
        }
    },
    "llm": {
        "provider": "openai",
        "config": {
            "api_key": "your-api-key",
            "model": "gpt-4"
        }
    },
    "embedder": {
        "provider": "openai",
        "config": {
            "api_key": "your-api-key",
            "model": "text-embedding-3-small"
        }
    },
    "graph_store": {
        "provider": "neo4j",
        "config": {
            "url": "neo4j+s://your-instance",
            "username": "neo4j",
            "password": "password"
        }
    },
    "history_db_path": "/path/to/history.db",
    "version": "v1.1",
    "custom_fact_extraction_prompt": "Optional custom prompt for fact extraction for memory",
    "custom_update_memory_prompt": "Optional custom prompt for update memory"
}

Run zentry Locally

Please refer to the example zentry with Ollama to run zentry locally.

Chat Completion

zentry can be easily integrated into chat applications to enhance conversational agents with structured memory. zentry’s APIs are designed to be compatible with OpenAI’s, with the goal of making it easy to leverage zentry in applications you may have already built. If you have a zentry API key, you can use it to initialize the client. Alternatively, you can initialize zentry without an API key if you’re using it locally. zentry supports several language models (LLMs) through integration with various providers.

Use zentry Platform

from zentry.proxy.main import zentry

client = zentry(api_key="m0-xxx")

# First interaction: Storing user preferences
messages = [
  {
    "role": "user",
    "content": "I love indian food but I cannot eat pizza since allergic to cheese."
  },
]
user_id = "alice"
chat_completion = client.chat.completions.create(messages=messages, model="gpt-4o-mini", user_id=user_id)
# Memory saved after this will look like: "Loves Indian food. Allergic to cheese and cannot eat pizza."

# Second interaction: Leveraging stored memory
messages = [
  {
    "role": "user",
    "content": "Suggest restaurants in San Francisco to eat.",
  }
]

chat_completion = client.chat.completions.create(messages=messages, model="gpt-4o-mini", user_id=user_id)
print(chat_completion.choices[0].message.content)
# Answer: You might enjoy Indian restaurants in San Francisco, such as Amber India, Dosa, or Curry Up Now, which offer delicious options without cheese.

In this example, you can see how the second response is tailored based on the information provided in the first interaction. zentry remembers the user’s preference for Indian food and their cheese allergy, using this information to provide more relevant and personalized restaurant suggestions in San Francisco.

Use zentry OSS

config = {
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "host": "localhost",
            "port": 6333,
        }
    },
}

client = zentry(config=config)

chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What's the capital of France?",
        }
    ],
    model="gpt-4o",
)

APIs

Get started with using zentry APIs in your applications. For more details, refer to the Platform. Here is an example of how to use zentry APIs:

import os
from zentry import MemoryClient

os.environ["zentry_API_KEY"] = "your-api-key"

client = MemoryClient() # get api_key from https://app.zentry.gg/

# Store messages
messages = [
    {"role": "user", "content": "Hi, I'm Alex. I'm a vegetarian and I'm allergic to nuts."},
    {"role": "assistant", "content": "Hello Alex! I've noted that you're a vegetarian and have a nut allergy. I'll keep this in mind for any food-related recommendations or discussions."}
]
result = client.add(messages, user_id="alex")
print(result)

# Retrieve memories
all_memories = client.get_all(user_id="alex")
print(all_memories)

# Search memories
query = "What do you know about me?"
related_memories = client.search(query, user_id="alex")

# Get memory history
history = client.history(memory_id="m1")
print(history)

Contributing

We welcome contributions to zentry! Here’s how you can contribute:

Fork the repository and create your branch from main.
Clone the forked repository to your local machine.
Install the project dependencies:
```
poetry install
```

Install pre-commit hooks:

pip install pre-commit  # If pre-commit is not already installed
pre-commit install

Make your changes and ensure they adhere to the project’s coding standards.
Run the tests locally:
```
poetry run pytest
```
If all tests pass, commit your changes and push to your fork.
Open a pull request with a clear title and description.

Please make sure your code follows our coding conventions and is well-documented. We appreciate your contributions to make zentry better! If you have any questions, please feel free to reach out to us using one of the following methods:

Join our community

GitHub

Ask questions on GitHub

Support

Talk to founders

Get Started

Core Concepts

Platform

Open Source

Contribution

Installation

Basic Usage

Initialize zentry

Store a Memory

Retrieve Memories

Search Memories

Update a Memory

Memory History

Delete Memory

Reset Memory

Configuration Parameters

Run zentry Locally

Chat Completion

Use zentry Platform

Use zentry OSS

APIs

Contributing

Telegram

GitHub

Support

Get Started

Core Concepts

Platform

Open Source

Contribution

​Installation

​Basic Usage

​Initialize zentry

​Store a Memory

​Retrieve Memories

​Search Memories

​Update a Memory

​Memory History

​Delete Memory

​Reset Memory

​Configuration Parameters

​Run zentry Locally

​Chat Completion

​Use zentry Platform

​Use zentry OSS

​APIs

​Contributing

Telegram

GitHub

Support

Installation

Basic Usage

Initialize zentry

Store a Memory

Retrieve Memories

Search Memories

Update a Memory

Memory History

Delete Memory

Reset Memory

Configuration Parameters

Run zentry Locally

Chat Completion

Use zentry Platform

Use zentry OSS

APIs

Contributing