AgentSmith

A Rust library for giving AI agents persistent, searchable memory that survives restarts.

Author's bio: 👋😀 Hi, I'm CryptoPatrick! I'm currently enrolled as an Undergraduate student in Mathematics, at Chalmers & the University of Gothenburg, Sweden.
If you have any questions or need more info, then please join my Discord Channel: AiMath

What is AgentSmith • Features • How To Use • Documentation • License

🛎 Important Notices

• Framework Support: Currently designed for Rig agents, but extensible to other frameworks
• Storage: Uses SQLite for persistent storage with full-text search capabilities
• Inspired by Atuin: Brings the power of Atuin's searchable shell history to AI agents

:pushpin: Table of Contents

🤔 What is AgentSmith

agentsmith is a Rust library that provides AI agents with persistent, fuzzy-searchable, metadata-rich memory that survives process restarts. Inspired by Atuin for shell history, AgentSmith ensures your agents never forget past conversations.

Built specifically for Rig agents, AgentSmith wraps your existing agents with a memory layer that automatically:

• Records all conversations to a SQLite database
• Enables fuzzy search across historical interactions
• Provides session management for organizing conversations
• Allows agents to recall relevant context from past discussions

Use Cases

• Persistent AI Assistants: Build chatbots that remember users across sessions
• Context-Aware Agents: Enable agents to reference past conversations naturally
• Conversation Analytics: Search and analyze agent interactions over time
• Session Management: Organize conversations by session for different contexts
• Agent Memory Research: Experiment with long-term memory for AI agents

📷 Features

agentsmith provides a complete memory layer for AI agents with persistent storage and intelligent retrieval:

🔧 Core Functionality

• Persistent History: Automatic storage of all agent interactions in SQLite
• Fuzzy Search: Full-text search across conversation history with relevance ranking
• Session Management: Group conversations into sessions for different contexts
• Metadata Tracking: Store timestamps, roles, and custom metadata with each interaction

🧠 Memory Capabilities

• Automatic Recording: All agent interactions are automatically saved
• Smart Retrieval: Retrieve recent messages or search by content
• Context Injection: Automatically include relevant past context in conversations
• Cross-Session Search: Search across all conversations or within specific sessions

🤖 Smart Agent Features

• Transparent Wrapping: Drop-in wrapper for existing Rig agents
• Automatic Context: Agents automatically recall relevant past interactions
• Session Summaries: Generate summaries of conversation sessions
• Conversation History: Access chronological history of interactions

💾 Persistence

• SQLite Storage: Reliable, file-based persistence with no external dependencies
• Migration Support: Built-in database schema migrations
• Session Continuity: Resume conversations across process restarts
• Export Capabilities: Import/export conversation history

🚙 How to Use

Installation

Add agentsmith to your Cargo.toml:

[dependencies]
agentsmith = "0.1"

Or install with cargo:

cargo add agentsmith

Basic Example

use agentsmith::{AgentHistory, SmartAgent};
use rig::providers::openai;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create persistent history
    let history = AgentHistory::new("my_agent.db", Some("session-123")).await?;

    // Create your Rig agent
    let client = openai::Client::new(&std::env::var("OPENAI_API_KEY")?);
    let agent = client
        .agent("gpt-4")
        .preamble("You are a helpful AI assistant with a perfect memory.")
        .build();

    // Wrap with SmartAgent for automatic memory
    let mut smart_agent = SmartAgent::new(agent, history);

    // Chat with automatic recall of relevant past interactions
    let reply = smart_agent.chat("How did we fix the JSON parsing bug?").await?;
    println!("Agent: {}", reply);

    Ok(())
}

Advanced Usage

use agentsmith::{AgentHistory, Trace};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create history with custom session ID
    let history = AgentHistory::new("./chat.db", Some("debug-session")).await?;

    // Search past conversations
    let results = history.search("bug fix", 10, false).await?;
    for trace in results {
        println!("[{}] {}: {}",
            trace.created_at.format("%Y-%m-%d %H:%M:%S"),
            trace.role,
            trace.content
        );
    }

    // Get recent messages
    let recent = history.recent(5).await?;
    println!("Found {} recent messages", recent.len());

    // Manually add traces
    history.add_trace("user", "What's the status?").await?;
    history.add_trace("assistant", "All systems operational").await?;

    Ok(())
}

🧪 Examples

The repository includes several examples demonstrating different features:

# Persistent chat REPL that remembers across restarts
cargo run --example persistent_chat

# Demonstrate Atuin-style search capabilities
cargo run --example atuin_search_demo

# Import conversation logs from other sources
cargo run --example import_old_logs

# Basic usage example
cargo run --example basic

🧪 Testing

Run the test suite:

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

📚 Documentation

Comprehensive documentation is available at docs.rs/agentsmith, including:

• API reference for all public types and functions
• Tutorial on wrapping Rig agents with persistent memory
• Examples of searching and managing conversation history
• Best practices for session management

🖊 Author

CryptoPatrick

Keybase Verification: https://keybase.io/cryptopatrick/sigs/8epNh5h2FtIX1UNNmf8YQ-k33M8J-Md4LnAN

🐣 Support

Leave a ⭐ if you think this project is cool.

🗄 License

This project is licensed under MIT. See LICENSE for details.