AIMemo

Memory System for AI Conversations

AIMemo is a lightweight memory layer that enables AI agents to remember context across conversations. Build AI applications that truly understand and remember your users.

🚀 Features

• Automatic Memory: Intercepts LLM calls and injects relevant context
• Multiple Backends: SQLite, PostgreSQL support out of the box
• Zero Config: Works with sensible defaults, configure when needed
• LLM Agnostic: Supports OpenAI, Anthropic, and more
• Namespace Isolation: Perfect for multi-user applications
• Full-Text Search: Fast memory retrieval with FTS5/PostgreSQL search

📦 Installation

pip install aimemo

For PostgreSQL support:

pip install aimemo[postgres]

⚡ Quick Start

from aimemo import AIMemo
from openai import OpenAI

# Initialize AIMemo
aimemo = AIMemo()
aimemo.enable()

# Use OpenAI normally - memory is automatic!
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "I'm building a FastAPI project"}]
)

# Later conversation - context is automatically injected
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "How do I add authentication?"}]
)
# The model remembers your FastAPI project!

💡 Use Cases

• Personal AI Assistants: Remember user preferences and history
• Customer Support Bots: Maintain context across support sessions
• Research Assistants: Keep track of research topics and findings
• Multi-Agent Systems: Share memory between multiple AI agents
• Learning Apps: Track student progress and learning patterns

🔧 Configuration

Database Options

SQLite (default):

from aimemo import AIMemo

aimemo = AIMemo()  # Uses aimemo.db by default

PostgreSQL:

from aimemo import AIMemo, PostgresStore

store = PostgresStore("postgresql://user:pass@localhost/aimemo")
aimemo = AIMemo(store=store)

Environment Variables

export AIMEMO_DB_PATH="./my_memory.db"
export AIMEMO_MAX_CONTEXT=10

Manual Memory Management

from aimemo import AIMemo

aimemo = AIMemo(namespace="user_123")

# Add memories manually
aimemo.add_memory(
    content="User prefers dark mode",
    tags=["preference", "ui"],
    metadata={"priority": "high"}
)

# Search memories
results = aimemo.search("dark mode", limit=5)

# Get formatted context
context = aimemo.get_context("user interface preferences")

Multi-User Applications

from aimemo import AIMemo

# Each user gets their own namespace
user_memory = AIMemo(namespace=f"user_{user_id}")
user_memory.enable()

# Memories are isolated per user

📚 Examples

Check out the examples/ directory:

• basic_usage.py - Simple conversation with memory
• manual_memory.py - Manual memory management
• postgres_example.py - Using PostgreSQL backend
• context_manager.py - Context manager pattern

🧪 Testing

pip install pytest
pytest tests/

🛠️ Development

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black aimemo tests examples

📖 Documentation

Full documentation is available in the docs/ directory:

• Quick Start Guide - Get started in 5 minutes
• Configuration Guide - Configure AIMemo for your needs
• Architecture Overview - How AIMemo works under the hood
• API Reference - Complete API documentation
• Storage Backends - Database configuration details
• Examples - More code examples and use cases
• Troubleshooting - Common issues and solutions

Development & Planning

• ROADMAP.md - Strategic roadmap and future plans
• TODO.md - Actionable tasks and sprint planning
• IMPLEMENTATION_GUIDE.md - Implementation guide for contributors
• SUMMARY.md - Development summary and quick overview

Core API

AIMemo

• enable() - Start intercepting LLM calls
• disable() - Stop intercepting
• add_memory(content, metadata, tags) - Add memory manually
• search(query, limit) - Search memories
• get_context(query, limit) - Get formatted context
• clear(namespace) - Clear memories

Storage Backends

• SQLiteStore(db_path) - SQLite storage
• PostgresStore(connection_string) - PostgreSQL storage

Architecture

AIMemo works by intercepting LLM API calls:

1. Pre-call: Searches relevant memories based on user query
2. Injection: Adds context to the conversation
3. Post-call: Stores the conversation for future reference

All automatically, with zero code changes!

🤝 Contributing

We love contributions! ❤️ AIMemo is an open-source project and we welcome contributions of all kinds:

• 🐛 Bug Reports: Found a bug? Open an issue
• 💡 Feature Requests: Have an idea? Share it with us
• 📝 Documentation: Help improve our docs
• 🔧 Code: Submit a Pull Request

How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: pytest tests/
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/gianghungtien/aimemo.git
cd aimemo

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black aimemo tests examples

First time contributing? Check out issues labeled good first issue to get started!

Contributors

Thanks to all the amazing people who have contributed to AIMemo! 🙏

📄 License

MIT License - see LICENSE file for details.

🙋 Support & Community

Need help? We're here for you!

• 💬 GitHub Discussions: Ask questions and share ideas
• 🐛 GitHub Issues: Report bugs or request features
• 📧 Email: gianghungtien@gmail.com

Show Your Support

If you find AIMemo helpful, please consider:

• ⭐ Star this repository to show your support
• 🐦 Share it with your friends and colleagues
• 📝 Write about it in your blog or social media
• 🤝 Contribute to make it even better