Asterix

Stateful AI agents with editable memory blocks and persistent storage.

Note: Asterix is in Beta (v0.2.1). Core features are stable and production-ready. Enhanced features and optimizations are in active development.

Asterix is a lightweight Python library for building AI agents that can remember, learn, and persist their state across sessions. No servers required - just pip install and start building.

Features

• Editable Memory Blocks - Agents can read and write their own memory via built-in tools
• Persistent Storage - State saves across sessions (JSON/SQLite backends)
• Semantic Search - Qdrant Cloud integration for long-term memory retrieval
• Enhanced Tool System - Easy decorator pattern with parameter validation, retry logic, and categories
• Custom System Prompts - Override the base system prompt for specialized agent behavior
• Tool Call Callbacks - Before/after hooks for human-in-the-loop approval and audit logging
• Step-by-Step Progress Callbacks - Stream heartbeat loop progress via on_step callback
• Conversation History API - Retrieve conversation history with get_history(limit=)
• Auto-Documentation - Tools automatically generate markdown/JSON documentation
• Smart Error Handling - Helpful error messages with suggestions and context
• Multi-Model Support - Works with Gemini, Groq, OpenAI, and extensible to others
• No Server Required - Pure Python library, runs anywhere

Quick Start

Installation

pip install asterix-agent

Or with UV (faster):

uv pip install asterix-agent

Basic Usage

from asterix import Agent, BlockConfig

# Create an agent with custom memory blocks
agent = Agent(
    blocks={
        "task": BlockConfig(size=1500, priority=1),
        "notes": BlockConfig(size=1000, priority=2)
    },
    model="gemini/gemini-2.5-flash"  # Default model
)

# Chat with your agent
response = agent.chat("Hello! Remember that I prefer Python over JavaScript.")
print(response)

# Agent automatically updates its memory
# Memory persists across conversations

Add Custom Tools

@agent.tool(name="read_file", description="Read a file from disk")
def read_file(filepath: str) -> str:
    with open(filepath, 'r') as f:
        return f.read()

# Now your agent can read files
response = agent.chat("Read config.yaml and summarize the settings")

Save & Load State

# Save agent state
agent.save_state()

# Later session - load previous state
agent = Agent.load_state("agent_id")
agent.chat("What were we discussing?")  # Remembers everything!

Documentation

Comprehensive documentation is available in the docs/ directory:

Core Concepts

• Memory System - How agent memory works (blocks, archival, conversation search)
• Tool System - Creating and using tools (validation, categories, retry logic)
• Storage Backends - State persistence (JSON, SQLite, custom backends)
• Configuration - Environment variables, YAML, and Python configuration

Guides

• Examples Guide - Walkthrough of all examples with explanations
• API Reference - Complete API documentation

Quick Links

• Environment Setup
• YAML Configuration Template
• Built-in Memory Tools
• Custom Tool Development
• JSON vs SQLite Backends

Examples

Complete working examples in examples/:

# Clone and setup
git clone https://github.com/adityasarade/Asterix.git
cd Asterix && pip install -e .

# Run examples
python examples/basic_chat.py              # Simple conversation
python examples/custom_tools.py            # Tool registration
python examples/persistent_agent.py        # JSON persistence
python examples/persistent_agent_sqlite.py # SQLite persistence
python examples/cli_agent.py               # Full-featured CLI

See the Examples Guide for detailed walkthroughs.

🧪 Testing

pip install -e ".[dev]"
pytest --cov=asterix --cov-report=html

Project Status

Current Version: 0.2.1 (Beta)

Roadmap:

• Core agent implementation
• Memory tools system
• State persistence (JSON & SQLite)
• Qdrant integration
• Enhanced tool system with validation
• Auto-documentation
• Multi-model support (Gemini, Groq, OpenAI)
• OSCAR integration (callbacks, system prompts, history API)
• Gemini SDK migration (google-genai v1.x)
• Vertex AI support (dual-mode Gemini auth)
• Performance optimizations
• Advanced monitoring
• Streaming responses
• Multi-agent collaboration
• Additional backends (Redis, PostgreSQL)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m 'Add your feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Gemini, Groq, and OpenAI
• Vector storage by Qdrant
• Inspired by Letta

Support

• Documentation: Full documentation with guides and API reference
• Issues: GitHub Issues - Report bugs or request features
• Examples: Examples directory - Working code examples
• Changelog: CHANGELOG.md - Version history and updates

So that everyone can build better agents without worrying about memory (Let's hope OpenAI doesn't make this library meaningless)