Project O is a self-evolving AI agent that uses Letta's memory architecture to achieve true autonomous evolution. Built in Gerbil Scheme with Elixir/OTP supervision, it can autonomously improve itself while maintaining memory of its evolution history.
Core Innovation: Leverages Letta's stateful memory model and extends it with autonomous self-evolution capabilities. Note: memos is a fork of Letta.
- Autonomous Evolution: Agent can modify its own code during sleep-time compute
- Stateful Memory: Remembers evolution history and reflects on changes
- Shadow Testing: Safe evolution experiments via Elixir supervision
- Evolution Tools: Self-modification, performance analysis, rollback
- Core Memory Blocks: Stable identity with editable persona/human memory
- Archival Memory: Long-term storage with semantic search for evolution history
- Autonomous Compute: Self-directed thinking and evolution without human intervention
- Active Memory Management: Agent can modify its own knowledge base
- Multi-Provider LLM: OpenAI, Anthropic, Groq, Ollama, and more
- Custom Tools: User-defined functions with sandbox execution
- Fault Tolerance: Automatic crash recovery via Elixir/OTP supervision
- REST API: Full-featured API for agent management
- PostgreSQL: Persistent storage with pgvector for semantic search
┌─────────────────────────────────────────────────────────┐
│ Elixir Supervision Layer │
│ • Fault tolerance & crash recovery │
│ • State persistence (checkpoints + WAL) │
│ • Shadow testing for safe evolution │
│ • Database operations (PostgreSQL) │
└─────────────────────────────────────────────────────────┘
↕ MessagePack
┌─────────────────────────────────────────────────────────┐
│ Gerbil Agent Application │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent │ │ Memory │ │ Tools │ │
│ │ Core │ │ System │ │ System │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ LLM │ │ Message │ │ HTTP │ │
│ │ Clients │ │ Manager │ │ Server │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
| Layer | Technology | Responsibility | Status |
|---|---|---|---|
| Supervision | Elixir/OTP | Fault tolerance, persistence | ✅ Done |
| Agent Core | Gerbil Scheme | Agent logic, DSL, lifecycle | ✅ Done |
| LLM Clients | Gerbil Scheme | OpenAI, Anthropic, Groq, Ollama | ✅ Done |
| HTTP Server | Gerbil Scheme | REST API endpoints | ✅ Done |
| Memory System | Gerbil Scheme | Blocks, archival, semantic search | ✅ Done |
| Tool System | Gerbil Scheme | Tool execution, sandbox, rules | ✅ Done |
| Database | PostgreSQL + Elixir | Persistent storage | ✅ Done |
| Vector Search | pgvector | Semantic search | ✅ Done |
| Agent Execution | Gerbil Scheme | Step-based execution, streaming | ✅ Done |
# Elixir & Erlang
brew install elixir # macOS
# or
apt-get install elixir # Ubuntu
# Gerbil Scheme
# Follow: https://cons.io/
# PostgreSQL (optional, for local development)
brew install postgresql@16# Clone repository
git clone <repository-url>
cd o
# Install Elixir dependencies
cd o_supervisor
mix deps.get
# Compile
mix compile
# Run tests
mix test
# Start in development
iex -S mix# Build and start all services
docker-compose up -d
# View logs
docker-compose logs -f o_supervisor
# Stop services
docker-compose down- README.md - This file (project overview)
- QUICKSTART.md - Quick start guide
- GETTING_STARTED.md - Detailed setup instructions
- Memos Alignment Analysis - 🔥 NEW: Alignment with memos
- Revised Roadmap - 🔥 NEW: 20-week implementation plan
- Architecture V2 - Complete architecture overview
- Elixir Integration Guide - Detailed implementation guide
- Phase 0 Completion - Elixir foundation ✅
- Phase 1 Completion - Gerbil agent core ✅
- Implementation Summary - Complete status
- FAQ - Frequently asked questions
- Quick Reference - Command reference
- Glossary - Terminology
- ADRs - Architecture Decision Records
# Run all tests
cd o_supervisor
mix test
# Run specific test
mix test test/memory_vault_test.exs
# Run with coverage
mix test --cover
# Run integration tests
mix test --only integration
# Run stress tests
mix test --only stresso/
├── README.md # This file
├── docs/ # Documentation
│ ├── ARCHITECTURE_V2.md # Architecture overview
│ ├── ELIXIR_INTEGRATION.md # Integration guide
│ ├── IMPLEMENTATION_CHECKLIST.md # Implementation steps
│ ├── adr/ # Architecture Decision Records
│ │ ├── 001-elixir-supervision-layer.md
│ │ ├── 002-communication-protocol.md
│ │ └── 003-checkpoint-strategy.md
│ └── protocol/ # Protocol specifications
│ └── MESSAGE_SCHEMA.md
├── o_supervisor/ # Elixir supervision layer
│ ├── mix.exs # Elixir project config
│ ├── config/ # Configuration files
│ ├── lib/ # Elixir source code
│ │ └── o_supervisor/
│ │ ├── application.ex # Application supervisor
│ │ ├── gerbil_manager.ex # Gerbil process manager
│ │ ├── memory_vault.ex # State persistence
│ │ ├── wal_manager.ex # Write-Ahead Log
│ │ ├── health_monitor.ex # Metrics collection
│ │ ├── evolution_arbiter.ex # Shadow testing
│ │ ├── traffic_splitter.ex # A/B testing
│ │ └── telemetry.ex # Telemetry setup
│ └── test/ # Tests
├── gerbil/ # Gerbil agent code
│ ├── agent/
│ │ ├── core.ss # Agent structure and lifecycle
│ │ ├── dsl.ss # DSL macros
│ │ ├── state.ss # State management
│ │ ├── memory.ss # Memory system
│ │ ├── tools.ss # Tool framework
│ │ └── elixir-bridge.ss # Elixir communication bridge
│ ├── test/
│ │ └── integration-test.ss # Integration tests
│ └── examples/
│ └── simple-agent.ss # Example agents
├── zig/ # Zig infrastructure modules
├── rust/ # Rust compute modules
├── docker-compose.yml # Docker deployment
└── data/ # Runtime data
├── checkpoints/ # State checkpoints
├── wal/ # Write-Ahead Logs
└── logs/ # Application logs
- Elixir supervision layer (8 modules)
- Fault tolerance & crash recovery
- Checkpoint + WAL persistence
- Shadow testing infrastructure
- Docker deployment + CI/CD
- Agent lifecycle management
- DSL (defagent, deftool, when->)
- State management with context
- Basic memory system
- Tool framework
- Integration tests (28+ cases)
- Example agents (5 demos)
- OpenAI & Anthropic clients
- Groq & Ollama clients
- Unified LLM client interface
- HTTP server with routing
- REST API endpoints (agents, messages)
- PostgreSQL schema (Letta-compatible)
- Gerbil-Elixir database protocol
- Message persistence & retrieval
- Message streaming (SSE)
- Memory blocks (persona, human, custom)
- Core memory operations
- Archival memory with search
- Semantic search (pgvector)
- Core tools (send_message, search, etc.)
- Memory tools (append, replace, patch)
- Tool execution sandbox
- Tool rules & approval workflow
- Step-based execution
- LLM inference with tool calls
- Context window management
- Streaming execution
- Performance optimization
See Revised Roadmap for detailed week-by-week plan.
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Elixir: Follow Elixir Style Guide
- Gerbil: Follow Scheme conventions
- Zig: Follow Zig Style Guide
- Rust: Use
rustfmt
| Metric | Target | Current | Status |
|---|---|---|---|
| Request latency (p50) | < 15ms | TBD | ⏳ |
| Request latency (p99) | < 50ms | TBD | ⏳ |
| Throughput | > 5000 QPS | TBD | ⏳ |
| Crash recovery time | < 100ms | TBD | ⏳ |
| Memory per instance | < 150MB | TBD | ⏳ |
- Input validation on all messages
- Sandboxed code execution
- Resource limits per shadow instance
- Encrypted data at rest and in transit
[Specify your license here]
- Elixir/OTP: For the battle-tested supervision trees
- Gerbil Scheme: For powerful metaprogramming capabilities
- Zig: For fast, safe infrastructure code
- Rust: For high-performance compute operations
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Status: All Phases Complete ✅ (Phases 0-6, Weeks 1-20) Version: 1.0.0 Last Updated: 2026-01-16
Project O has successfully completed all 20 weeks of the roadmap!
Delivered (~30,290 lines of code across 72 files):
- ✅ Phase 2 (Weeks 1-4): LLM Integration & HTTP Server
- ✅ Phase 3 (Weeks 5-8): Database & Message System
- ✅ Phase 4 (Weeks 9-12): Advanced Memory System
- ✅ Phase 5 (Weeks 13-16): Tool System Enhancement
- ✅ Phase 6 (Weeks 17-20): Agent Execution Loop
Key Achievements:
- 🧠 Complete Letta-compatible memory system (core, archival, semantic search)
- 🔧 Full tool system with sandbox and approval workflow
- 🚀 Agent execution loop with streaming and performance optimization
- 📊 Comprehensive benchmarking system
- 📚 Complete documentation and test coverage
See Progress Summary for detailed breakdown.
Core Mission: Project O aims to achieve autonomous self-evolution through stateful memory!
Why Letta's Architecture?
- 🧠 Stateful Memory: Agent remembers its evolution history and can reflect
- 💤 Autonomous Compute: Agent can evolve independently without human intervention
- 🔄 Active Memory Management: Agent can modify its own knowledge base
- 📚 Archival Memory: Agent learns from past evolution attempts
Our Goal - Evolution, Not Imitation:
- 🎯 Beyond Letta: We're not copying Letta - we're building on its foundation to achieve true self-evolution
- 🧬 Autonomous Evolution: Agent can modify its own code and improve itself
- 🔬 Safe Experimentation: Elixir supervision enables risk-free evolution testing
- 📈 Continuous Improvement: Agent learns from each evolution attempt
Implementation Foundation:
- ✅ Phases 0-1: Fault tolerance foundation (enables safe evolution)
- ✅ Phases 2-3: Letta-compatible infrastructure (memory, tools, API)
- ✅ Phase 4: Advanced memory system (semantic search, archival)
- ✅ Phase 5: Tool system (self-modification capabilities)
- ✅ Phase 6: Agent execution loop (autonomous operation)
Note: memos is a fork of Letta. We build on Letta's architecture.
See:
- Progress Summary - Complete 20-week implementation details
- Revised Roadmap - Week-by-week implementation plan
Phase 1 (Gerbil Agent Core) completed with:
- ✅ 6 core modules (~3,650 lines)
- ✅ 7 test suites (28+ test cases)
- ✅ 5 example agents
- ✅ Complete documentation
See Phase 1 Completion Report for details.