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.
- 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_stepcallback - 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
pip install asterix-agentOr with UV (faster):
uv pip install asterix-agentfrom 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@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 agent state
agent.save_state()
# Later session - load previous state
agent = Agent.load_state("agent_id")
agent.chat("What were we discussing?") # Remembers everything!Comprehensive documentation is available in the docs/ directory:
- 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
- Examples Guide - Walkthrough of all examples with explanations
- API Reference - Complete API documentation
- Environment Setup
- YAML Configuration Template
- Built-in Memory Tools
- Custom Tool Development
- JSON vs SQLite Backends
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 CLISee the Examples Guide for detailed walkthroughs.
pip install -e ".[dev]"
pytest --cov=asterix --cov-report=htmlCurrent 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-genaiv1.x) - Vertex AI support (dual-mode Gemini auth)
- Performance optimizations
- Advanced monitoring
- Streaming responses
- Multi-agent collaboration
- Additional backends (Redis, PostgreSQL)
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- 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)