cuemap 0.3.0

Redis for AI Agents - High-performance temporal-associative memory

CueMap: Redis for AI Agents

High-performance, temporal-associative memory store.

You give us the cues, we give you the right memory at the right time.

Why CueMap?

Redis doesn't auto-serialize your data. It doesn't guess what you mean. It just stores keys and values blazing fast.

CueMap is the same philosophy for AI agent memory:

• ✅ You control the cues (tags)
• ✅ We handle the speed (sub-millisecond)
• ✅ No magic (predictable behavior)
• ✅ No dependencies (5KB SDK)

Installation

pip install cuemap

That's it. No ML models. No transformers. Just pure speed.

Quick Start

1. Start the Engine

docker run -p 8080:8080 cuemap/engine:latest

2. Use the SDK

from cuemap import CueMap

client = CueMap()

# Add a memory with cues
client.add(
    "The server password is abc123",
    cues=["server", "password", "credentials"]
)

# Recall by cues
results = client.recall(["server", "password"])
print(results[0].content)
# Output: "The server password is abc123"

Core API

Add Memory

memory_id = client.add(
    content="Meeting with John at 3pm",
    cues=["meeting", "john", "calendar", "today"]
)

Recall Memories

results = client.recall(
    cues=["meeting", "john"],
    limit=10
)

for result in results:
    print(f"{result.content} (score: {result.score})")

Reinforce Memory

# Make a memory more accessible
client.reinforce(memory_id, cues=["important", "urgent"])

How It Works

Temporal-Associative Retrieval

CueMap uses Iterative Deepening Intersection:

1. Intersection: Memories matching multiple cues rank higher
2. Recency: Recent memories are more accessible
3. Reinforcement: Frequently accessed memories stay "front of mind"

# Add memories
client.add("Pizza recipe", cues=["food", "italian"])
client.add("Pasta recipe", cues=["food", "italian"])
client.add("Sushi recipe", cues=["food", "japanese"])

# Query with multiple cues
results = client.recall(["food", "italian"])
# Returns: Pizza and Pasta (both match 2 cues)
# Sushi is filtered out (only matches 1 cue)

Performance (~1M memories)

• Write P99: 0.33ms
• Read P99: 0.37ms
• Throughput: 2,900+ ops/sec
• Accuracy: 100% (validated on 120 test scenarios)

Recipes

Recipe 1: Use with OpenAI

from cuemap import CueMap
import openai

client = CueMap()

def store_with_ai_tags(content: str):
    # Let OpenAI extract the cues
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{
            "role": "system",
            "content": "Extract 3-5 search tags from the text. Return as JSON array."
        }, {
            "role": "user",
            "content": content
        }]
    )
    
    cues = response.choices[0].message.content  # ["tag1", "tag2", ...]
    
    # Store in CueMap
    return client.add(content, cues=cues)

# Usage
store_with_ai_tags("I need to buy groceries this weekend")
# OpenAI extracts: ["shopping", "groceries", "weekend", "todo"]

Recipe 2: Use with LangChain

from cuemap import CueMap
from langchain.memory import BaseMemory

class CueMapMemory(BaseMemory):
    def __init__(self, cue_extractor):
        self.client = CueMap()
        self.extract_cues = cue_extractor
    
    def save_context(self, inputs, outputs):
        context = f"User: {inputs['input']}\nAI: {outputs['output']}"
        cues = self.extract_cues(context)
        self.client.add(context, cues=cues)
    
    def load_memory_variables(self, inputs):
        cues = self.extract_cues(inputs['input'])
        results = self.client.recall(cues, limit=5)
        return {"history": "\n".join([r.content for r in results])}

Recipe 3: Manual Cues (Production)

# For production: explicit, predictable cues
client.add(
    "Deploy command: kubectl apply -f deployment.yaml",
    cues=["deployment", "kubernetes", "commands", "devops"]
)

client.add(
    "API endpoint: https://api.example.com/v1/users",
    cues=["api", "endpoint", "users", "documentation"]
)

# Query with specific cues
client.recall(["deployment", "kubernetes"])
client.recall(["api", "users"])

Running the Engine

CueMap requires a running engine. Choose your deployment:

Option 1: Docker (Recommended)

docker run -p 8080:8080 cuemap/engine:latest

Option 2: From Source

git clone https://github.com/cuemap-dev/engine
cd engine
cargo build --release
./target/release/cuemap-rust --port 8080

Configuration

Connect to Engine

# Default (localhost)
client = CueMap()

# Custom URL
client = CueMap(url="http://your-server:8080")

# With authentication
client = CueMap(
    url="http://your-server:8080",
    api_key="your-secret-key"
)

Multi-tenancy

# Use project isolation
client = CueMap(
    url="http://your-server:8080",
    project_id="my-project"
)

Async Support

from cuemap import AsyncCueMap

async with AsyncCueMap() as client:
    await client.add("Note", cues=["work"])
    results = await client.recall(["work"])

Philosophy

What CueMap Does

✅ Fast storage - Sub-millisecond retrieval ✅ Temporal ordering - Recent memories prioritized ✅ Intersection scoring - Multi-cue matching ✅ Reinforcement - Move-to-front operation

What CueMap Doesn't Do

❌ Auto-tagging - You provide the cues ❌ Semantic search - Use your own embeddings ❌ LLM integration - Bring your own model ❌ Magic - Explicit and predictable

Why This Approach?

Redis Philosophy: Don't guess what the user wants. Provide primitives. Let them build.

CueMap Philosophy: Don't auto-extract cues. Don't auto-embed. Just store and retrieve fast.

Benefits:

• 🚀 5KB SDK (vs 500MB with ML models)
• ⚡ Instant install (1 second vs 5 minutes)
• 🎯 Predictable (no ML black boxes)
• 🔧 Flexible (works with any LLM/embedding model)

Comparison

Feature	CueMap	Vector DBs
Speed	0.37ms P99	200-500ms
SDK Size	5KB	500MB+
Dependencies	2	50+
Install Time	1 sec	5 min
Cue Control	Explicit	Auto (black box)
Temporal	✅ Built-in	❌ None

Documentation

• Engine Repository
• SDKs Repository
• Examples

License

MIT