The App-Dev Agent Memory Kernel
Give your AI agents a memory that actually remembers
Atomic Blueprint (ab) is a Python library that implements structured memory management for AI agent systems. Think of it as the "working memory" for your development agents—enabling them to remember context, learn from past interactions, and make better decisions over time.
Most AI agents are stateless—they forget everything between conversations. ab changes that.
- 🧠 Persistent Memory: Your agents remember past decisions, code changes, and user preferences
- 🔗 Structured Recall: Efficient, shape-based memory retrieval (RECALL:SHAPE system)
- 👥 Council of Selves: Multiple internal agents collaborate to provide better suggestions
- 🚀 Zero Setup: Works out of the box with SQLite—no database server needed
- 🎨 Flexible: Supports PostgreSQL, image storage, and custom integrations
No database setup required! ab uses SQLite by default—just install and use:
💡 New to ab? See docs/guides/QUICK_START.md for a 60-second guide!
🔧 Using uv? See docs/guides/README_UV.md for uv-specific setup (recommended).
import asyncio
from ab import ABClient
from uuid import uuid4
async def main():
# Works out of the box with SQLite (no setup needed!)
async with ABClient(project_id=uuid4()) as client:
# Store awareness
card_id = await client.store_awareness(
prompt="User wants to add authentication",
files=["src/auth.py"],
diffs="Added User model"
)
# Recall context
context = await client.recall_shape("architecture_context")
# Run council
result = await client.run_council(card_id)
print(f"Winner: {result.winner[0] if result.winner else 'None'}")
asyncio.run(main())Install uv (recommended) or use pip:
# Install uv (fast Python package installer)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or: brew install uv# With uv (recommended - automatically creates venv)
uv pip install ab
# Or with pip
pip install ab
# With PostgreSQL support
uv pip install ab[postgresql] # or: pip install ab[postgresql]
# Full install (PostgreSQL + migrations)
uv pip install ab[full] # or: pip install ab[full]# Clone repository
git clone https://github.com/hexcreator/ab.git
cd ab
# Create virtual environment and install dependencies
uv sync # Creates .venv and installs dependencies
# Activate virtual environment (optional, uv run works without it)
source .venv/bin/activate # macOS/Linux
.venv\Scripts\activate # Windows
# Or use uv run (no activation needed)
uv run python scripts/quick_start.pyThe default SQLite database is automatically created in .ab/ab.db in your current directory.
- 🎯 Zero Setup: Works out of the box with SQLite (no database server needed!)
- 📦 Self-Contained: Minimal dependencies, PostgreSQL optional
- 🧩 Structured Memory: Cards, Buffers, and Moments for organized memory storage
- 🔍 RECALL:SHAPE: Efficient, bounded retrieval with shape-based queries
- 👥 Council of Selves: Multiple internal agents providing ranked suggestions
- 🗂️ Project Scoping: Isolated memory per project/repo
- 🖼️ Image Storage: Flexible image storage with metadata extraction (optional)
- 🔌 Integration Ready: Hooks for Cursor IDE and generic agent systems
- 🔗 Graph Connections: RFS memory web with automatic relationship detection
- 🎨 Multi-Modal: Support for text, images, audio, and emotional states
Default (SQLite): No setup required, works immediately
client = ABClient() # Uses SQLite automaticallyPostgreSQL (optional, for production):
client = ABClient(db_url="postgresql://user:pass@localhost/ab")ab implements the Atomic Blueprint specification with:
- Core Entities: Project, Moment, Card, Buffer, SelfAgent, CardStats
- RECALL:SHAPE System: Structured retrieval with shape-based queries
- Council of Selves: Multiple internal agents (Architect, Executor, Historian, FeaturePlanner)
- Database Layer: SQLite (default) or PostgreSQL with SQLAlchemy and async support
- Storage Abstractions: Image storage (local, S3, reference-only)
- Graph Memory: RFS memory web with automatic connection detection
See the examples/ directory for creative use cases.
See docs/guides/README_EXAMPLES.md for examples overview.
01_basic_usage.py- Basic usage patterns07_cursor_extension.py- Cursor IDE integration (stable working memory for dev agents)05_graph_connections.py- Graph connections and RFS memory web
02_project_management.py- Project management with memory03_llm_memory.py- Enhance LLM conversations with persistent memory04_image_database.py- Multi-modal image database08_color_identification.py- Semantic memory for color experiences09_pokemon_environment.py- Long-term episodic memory for game AI10_llm_memory_effectiveness_testing.py- Objective metrics for memory effectiveness
Quick Commands:
# List all examples
python scripts/list_examples.py
# Run quick start
python scripts/quick_start.py
# Run an example
python scripts/run_example.py 01_basic_usageSee examples/README.md for detailed descriptions.
# Quick test run (recommended)
./scripts/run_tests.sh # macOS/Linux
.\scripts\run_tests.ps1 # Windows
# Or manually with uv
uv sync --extra dev
uv run pytest tests/ -v
# Run only unit tests
uv run pytest tests/unit/ -v
# Run with coverage
uv run pytest --cov=ab tests/Comprehensive documentation is available:
- API Reference - Complete API documentation
- Usage Guide - Usage patterns and examples
- Architecture - System architecture and design
- Quick Start - Get started in 60 seconds
- Examples - Practical code examples
Current: SQL (SQLite/PostgreSQL)
- ✅ Production ready
- ✅ ACID transactions
- ✅ Standard tooling
Alternative: Treeweb (Graph)
- 🔶 Proof of concept available
- Natural relationship traversal
- Graph-based queries
- See
examples/treeweb_storage.pyanddocs/STORAGE_BACKENDS.md
We welcome contributions! See docs/guides/CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
MIT License - see LICENSE for details.
Built with ❤️ for the AI agent development community.
Made with ⚛️ Atomic Blueprint
⭐ Star us on GitHub • 📖 Documentation • 🐛 Report Bug • 💡 Request Feature