Astreus - Docs

Welcome to Astreus

Welcome to Astreus

Astreus is a powerful and flexible AI Agent Framework designed to help you easily build, deploy, and manage intelligent conversational agents powered by large language models (LLMs) with advanced memory management, task orchestration, and plugin system.

What is Astreus?

Astreus provides a comprehensive set of tools and abstractions to create AI agents that can:

  • Hold complex, multi-turn conversations with real-time streaming
  • Manage structured chats with metadata and organization
  • Perform structured tasks and operations
  • Reason over data from multiple sources
  • Integrate with external systems through plugins
  • Maintain memory of past interactions with advanced session management
  • Access all components through a unified agent interface

Key Features

  • 🤖 Agent-Centric Architecture: Everything accessible through agent methods - no need for separate managers
  • ⚡ Real-Time Streaming: Built-in streaming chat with agent.chat({ stream: true }) for live responses
  • 💬 Chat Service: Advanced chat management with metadata, search, and organization
  • 🎭 Personality System: Create and manage distinct AI personalities with automatic integration
  • 🧠 Memory Storage: Hierarchical memory system with immediate, summarized, and persistent layers
  • 🎯 Task Execution: Intelligent task orchestration with dependency management
  • 🔌 Plugin Registry: Centralized plugin management with automatic tool registration
  • 🌐 Provider Client: Unified interface for multiple AI model providers
  • 🧩 Context Processor: Adaptive context window management with token budgeting
  • 📊 Multi-Provider Support: Works with OpenAI, Ollama, Claude (Anthropic), and Gemini (Google)
  • 🔍 RAG Support: Built-in Retrieval Augmented Generation with automatic tool creation
  • 🎨 Type Safety: Fully typed with TypeScript for better development experience
  • 📝 Professional Logging: Structured logging system with color-coded output and consistent formatting
  • ⚙️ Modular Configuration: Enhanced parameter validation, smart defaults, and module-specific configs
  • 🔄 Lazy Table Creation: Each module creates its own database tables when first used
  • 🖼️ Media Analysis: AI-powered image, document, and file analysis capabilities with context processing
  • 🎯 Intent Recognition: Intelligent tool selection using LLM-powered intent detection and context processing
  • 📋 Enhanced Database Management: Flexible table naming, automatic schema creation, and migration support with advanced memory storage
  • 🔧 Structured Responses: Built-in support for structured completion responses
  • 🧠 Adaptive Context Management: Hierarchical memory layers with intelligent token budgeting and compression

Agent-First Approach

With Astreus, everything revolves around the Agent with enhanced chat management:

// Create an agent with all capabilities including chat management
const agent = await createAgent({
  name: 'My Assistant',
  provider: myProvider,
  memory: myMemory,
  chat: myChatManager, // Chat management system
  tools: [customTool1, customTool2]
});

// Create and manage structured chats
const chat = await agent.createChat({
  chatId: "consultation-123",
  title: "Business Consultation",
  metadata: { type: "business", priority: "high" }
});

// Stream responses in real-time with chat IDs
await agent.chat({
  stream: true,
  message: "Hello!",
  chatId: "consultation-123",
  onChunk: (chunk) => console.log(chunk)
});

// Advanced chat management
const chats = await agent.listChats({ status: 'active', limit: 10 });
const stats = await agent.getChatStats();
const searchResults = await agent.searchChats({ query: "business" });

// Archive or delete chats
await agent.archiveChat("old-chat-id");
await agent.deleteChat("unwanted-chat-id");

// Access everything through the agent
const sessions = await agent.listSessions();
const history = await agent.getHistory("chat-123");
const provider = agent.getProvider();
const memory = agent.config.memory;

Database Architecture

Astreus uses a lazy table creation approach where each module automatically creates its required database tables when first used:

  • createMemory() creates the memories table
  • createChat() creates the chats table
  • createAgent() creates the agents table
  • createTask() creates the tasks table
  • createUser() creates the users table
  • createRAG() creates the RAG documents table

This eliminates the need for manual database schema setup and allows for custom table names per module.

Getting Started

Ready to create your first AI agent with advanced chat management? Visit our Quick Start Guide to set up Astreus and build your first conversational agent with streaming capabilities and chat organization in minutes.

Core Concepts

  • Agents - The heart of Astreus - unified interface for all operations including chat management
  • Memory Storage - Hierarchical memory system with immediate, summarized, and persistent layers
  • Chat Service - Advanced streaming chat system with real-time responses and metadata management
  • Task Execution - Intelligent task orchestration with dependency management and execution
  • Plugin Registry - Centralized plugin management with automatic tool registration
  • Provider Client - Unified interface for multiple AI model providers
  • Context Processor - Adaptive context window management with token budgeting
  • Media Analysis - AI-powered image, document, and file analysis capabilities
  • Intent Recognition - Intelligent tool selection using LLM-powered intent detection
  • RAG (Retrieval Augmented Generation) - Automatic document search tools with Vector and Document RAG

Official Plugins

  • X Plugin - Interact with the X (formerly Twitter) platform
  • WhatsApp Plugin - Send messages via WhatsApp Business API
  • Resend Plugin - Send professional emails through Resend
  • EVM Plugin - Interact with Ethereum and EVM-compatible blockchains

How is this guide?