Official Python examples for ToonDB - the high-performance embedded database for AI applications. This repository showcases integration patterns with popular agent frameworks and demonstrates ToonDB's unique features.
toondb-python-examples/
├── agent_memory/ # Production agent memory system with HNSW index
├── azure_openai/ # Azure OpenAI integration examples
├── complete_examples/ # Framework integrations (LangGraph, AutoGen, CrewAI)
├── context_builder/ # Token-budget aware context assembly
├── ecommerce/ # eCommerce product catalog RAG
├── langgraph/ # LangGraph checkpointer and memory
├── podcast/ # Podcast transcript search
├── rag/ # Complete RAG pipeline
├── wizard_of_oz/ # Long-form text ingestion
└── zep/ # Zep-compatible examples
- Python 3.10+ installed
- ToonDB Python SDK:
toondb-client>=0.3.3
pip install toondb-client>=0.3.3Production-ready agent memory system with vector search and HNSW index.
Features:
- Long-term memory with semantic search
- Session-based memory management
- Time-weighted retrieval
- Performance tracking and metrics
- HNSW vector index for fast similarity search
Use Cases: Multi-turn conversations, customer support agents, research assistants
cd agent_memory
pip install -r requirements.txt
python main.pyBest for: Building stateful LangGraph agents with persistent memory.
Features:
- Custom ToonDB checkpointer for graph state
- Long-term memory store for user interactions
- Time-weighted context retrieval
- Seamless LangGraph integration
cd langgraph
pip install -r requirements.txt
python agent_with_toondb.pyBest for: Managing LLM context under strict token budgets.
Features:
- Priority-based content truncation
- Token budget management
- Intelligent context assembly
- System + user + history + retrieval
Demonstrated Scenarios:
- Ample budget (4000 tokens)
- Tight budget (500 tokens)
- ToonDB integration with TOON format
cd context_builder
pip install -r requirements.txt
python runner.pyComplete production RAG system with document ingestion, chunking, and query pipeline.
Features:
- Document ingestion and chunking
- Azure OpenAI embeddings
- Vector search with ToonDB
- Generation with context
cd rag
pip install -r requirements.txt
python main.pyBest for: Product catalogs, shopping assistants, recommendation systems.
Features:
- Hybrid search (semantic + metadata filtering)
- TOON format for compact results
- Structured product data ingestion
- 100% accuracy on test queries
cd ecommerce
pip install -r requirements.txt
python runner.pyBest for: Fact retrieval systems with Azure OpenAI.
Features:
- Entity-focused retrieval (Kamala Harris, Gavin Newsom)
- High-precision fact extraction
- Azure OpenAI embeddings and chat
- 100% accuracy on political facts
cd azure_openai
pip install -r requirements.txt
python runner.pyBest for: Long-context narrative understanding, book ingestion.
Features:
- Paragraph-based chunking
- Semantic search over narrative text
- Character and plot retrieval
- 100% accuracy on story queries
cd wizard_of_oz
pip install -r requirements.txt
python runner.pyBest for: Audio transcripts, meeting notes, multi-speaker dialogue.
Features:
- Speaker attribution parsing
- Timestamp preservation
- Turn-based segmentation
- 100% accuracy on speaker/topic queries
cd podcast
pip install -r requirements.txt
python runner.pyMulti-framework integrations showing ToonDB with various agent frameworks.
Included:
- LangGraph agent with ToonDB memory
- AutoGen multi-agent with ToonDB
- Chat history management
- Graph-based examples
cd complete_examples
pip install -r requirements.txt
# Run individual examples
python langgraph_agent_with_toondb.pyBest for: Users migrating from Zep or needing entity-centric memory.
Features:
- Entity extraction and storage
- User profile management
- Conversation thread tracking
- Zep-compatible API patterns
cd zep
pip install -r requirements.txt
python toondb_simple.pyInteractive Jupyter notebooks for learning ToonDB features through hands-on examples.
RAG + SQL + Transactions
Learn how to build an AI support agent with:
- SQL queries for order data
- KV storage for user preferences
- Vector RAG with policy retrieval
- TOON encoding (40-67% token savings)
- ACID transactions
Key Concepts: execute_sql(), KV storage, vector collections, ContextQuery, TOON format, transactions
Multi-Agent IPC
Learn how to build coordinated multi-process systems with:
- IPC mode (Unix socket)
- Shared state across processes
- Namespace isolation
- Hybrid retrieval (vector + keyword with RRF)
- ACID state machines
Key Concepts: IPC mode, IpcClient, namespaces, hybrid search, state transitions
Spreadsheet + AI Analysis
Learn how to build data analysis agents with:
- CSV ingestion to SQL
- TOON vs JSON token comparison (with proof!)
- Vector search over text fields
- Token-budgeted context assembly
- Churn prediction analysis
Key Concepts: CSV → SQL, TOON encoding, token savings measurement, semantic search
- TOON Format: Token-efficient output format (
Database.to_toon()) - Vector Search: Built-in HNSW index for semantic similarity
- ACID Transactions: Group commits with Snapshot Isolation
- Columnar Storage: Efficient projection-based reads
- SQL Support: Optional SQL interface via IPC mode
- Embedded Mode: Zero-config, file-based database
All examples include accuracy_test.py scripts with verified results:
| Example | Accuracy | Test Cases |
|---|---|---|
| eCommerce | 100% | 4/4 |
| Azure OpenAI | 100% | 4/4 |
| Wizard of Oz | 100% | 3/3 |
| Podcast | 100% | 4/4 |
We welcome contributions! Please submit Pull Requests with:
- New example implementations
- Improvements to existing examples
- Documentation enhancements
- Bug fixes
Apache License 2.0 - see the LICENSE file for details.
- toondb/toondb - Main ToonDB repository
- toondb/toondb-go - Go SDK
- toondb/toondb-golang-examples - Go examples
- toondb/toondb-examples - Multi-language examples
Some of the agent memory examples (Wizard of Oz, Podcast, Zep ports) are referenced and adapted from the following projects: