cluttr 0.1.0

Long-term memory for AI agents using PostgreSQL vector storage

Cluttr

Long-term memory for AI agents using PostgreSQL vector storage.

🌐 https://www.cluttr.co

Installation

# From PyPI
uv add cluttr

# From GitHub
uv add git+https://github.com/mkhizeryounas/cluttr.git

Quick Start

import asyncio
from cluttr import Cluttr

async def main():
    # Configure
    config = {
        "vector_db": {
            "engine": "postgres",
            "host": "localhost",
            "port": 5432,
            "database": "cluttr",
            "user": "postgres",
            "password": "secret",
        },
        "llm": {
            "provider": "bedrock",
            "region": "us-east-1",
        },
    }

    # Create memory instance
    memory = Cluttr(config)

    async with memory:
        # Add memories from a conversation
        messages = [
            {"role": "user", "content": "I prefer Python over JavaScript"},
            {"role": "assistant", "content": "Got it! I'll remember that you prefer Python."},
        ]

        await memory.add(messages, user_id="user_123", agent_id="agent_456")

        # Search for relevant memories
        results = await memory.search(
            "What programming language does the user prefer?",
            k=5,
            user_id="user_123",
            agent_id="agent_456",
        )
        for r in results:
            print(f"[{r.similarity:.2f}] {r.memory.content}")

asyncio.run(main())

Configuration

AWS Bedrock Provider

config = {
    "vector_db": {
        "engine": "postgres",  # Only 'postgres' supported
        "host": "localhost",
        "port": 5432,
        "database": "cluttr",
        "user": "postgres",
        "password": "secret",
        # OR use connection_string instead:
        # "connection_string": "postgresql://user:pass@host:port/db",
    },
    "llm": {
        "provider": "bedrock",
        "region": "us-east-1",
        "model": "anthropic.claude-3-haiku-20240307-v1:0",  # Optional
        "embedding_model": "amazon.titan-embed-text-v2:0",  # Optional
        "aws_access_key_id": "...",  # Optional, uses default credentials
        "aws_secret_access_key": "...",
        "aws_session_token": "...",
    },
    "similarity_threshold": 0.95,  # Optional, for duplicate detection
}

memory = Cluttr(config)

OpenAI Provider

config = {
    "vector_db": {
        "engine": "postgres",
        "host": "localhost",
        "port": 5432,
        "database": "cluttr",
        "user": "postgres",
        "password": "secret",
    },
    "llm": {
        "provider": "openai",
        "api_key": "sk-...",
        "model": "gpt-4o-mini",  # Optional, default: gpt-4o-mini
        "embedding_model": "text-embedding-3-small",  # Optional
        "base_url": "...",  # Optional, for custom endpoints
    },
    "similarity_threshold": 0.95,  # Optional
}

memory = Cluttr(config)

Usage

Adding Memories

# Add with specific user/agent
await memory.add(messages, user_id="user_123", agent_id="agent_456")

# Add with defaults (user_id="default_user", agent_id="default_agent")
await memory.add(messages)

Searching Memories

# Search with specific user/agent
results = await memory.search(
    "What does the user like?",
    k=10,
    user_id="user_123",
    agent_id="agent_456",
)

# Search with defaults
results = await memory.search("query", k=5)

# Access results
for result in results:
    print(result.memory.content)
    print(result.similarity)

Image Support

Images in messages are automatically summarized:

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Here's my system architecture"},
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/diagram.png"}
            }
        ]
    }
]

await memory.add(messages)

Supported image formats:

• Base64 encoded images
• URLs (http/https)
• Local file paths

Features

• Automatic Memory Extraction: LLM extracts important facts from conversations
• Smart Query Expansion: Search queries are automatically optimized for vector matching
• Duplicate Detection: LLM-powered deduplication prevents redundant memories
• Image Support: Images are automatically summarized and stored as searchable memories
• PostgreSQL + pgvector: Battle-tested vector similarity search
• Multiple Providers: AWS Bedrock (Claude + Titan) and OpenAI (GPT-4o-mini)
• Async Native: Full async/await support

Development

# Clone the repository
git clone https://github.com/mkhizeryounas/cluttr.git
cd cluttr

# Install dependencies
uv sync --all-extras

# Install package in editable mode (required to run examples)
uv pip install -e . --force-reinstall

# Run examples
uv run python examples/chat_with_memory_openai.py

Requirements

• Python 3.11+
• PostgreSQL with pgvector extension
• AWS credentials (for Bedrock) or OpenAI API key

Supabase Setup

Cluttr works with Supabase as the PostgreSQL backend.

1. Enable pgvector Extension

In your Supabase dashboard, go to Database → Extensions and enable the vector extension.

Or run this SQL:

CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA extensions;

2. Configure Connection

config = {
    "vector_db": {
        "engine": "postgres",
        "host": "db.<project-ref>.supabase.co",
        "port": 5432,
        "database": "postgres",
        "user": "postgres",
        "password": "<your-db-password>",
    },
    "llm": {
        "provider": "openai",
        "api_key": "sk-...",
    },
}

Or use a connection string:

config = {
    "vector_db": {
        "engine": "postgres",
        "connection_string": "postgresql://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres",
    },
    "llm": {
        "provider": "openai",
        "api_key": "sk-...",
    },
}

3. Table Schema

Cluttr automatically creates the cluttr_memories table on first connection:

CREATE TABLE IF NOT EXISTS cluttr_memories (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    agent_id TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1536),  -- 1536 for OpenAI, 1024 for Bedrock
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

License

MIT