Basic Usage

Learn Memori's core concepts with practical examples.

Core Concepts

Memory Types

Memory Modes

How It Works

graph LR
    A[LLM Conversation] --> B[Universal Recording]
    B --> C[Memory Agent Processing]
    C --> D[Structured Storage]
    D --> E[Context Injection]
    E --> A

1. Universal Recording: All LLM conversations automatically captured
2. Memory Processing: Pydantic-based entity extraction and categorization
3. Structured Storage: Organized in SQLite/PostgreSQL/MySQL
4. Context Injection: Relevant memories added to future conversations

Simple Example

from memori import Memori

# Initialize with conscious ingestion (recommended)
memori = Memori(
    database_connect="sqlite:///my_project.db",
    conscious_ingest=True,  # Enable intelligent context injection
    auto_ingest=False,      # Optional: dynamic memory search
    openai_api_key="sk-..."
)

# Enable recording
memori.enable()

# Use any LLM library
from litellm import completion

# Establish preferences
completion(
    model="gpt-4o-mini",
    messages=[{
        "role": "user",
        "content": "I'm a Python developer who prefers clean, well-documented code"
    }]
)

# Later conversation - preferences remembered
completion(
    model="gpt-4o-mini",
    messages=[{
        "role": "user",
        "content": "Help me write a function to validate emails"
    }]
)
# Response will include clean code with documentation!

Memory Modes Explained

Conscious Ingest Mode

memori = Memori(conscious_ingest=True)

• One-shot injection: Essential memories injected once at conversation start
• Background analysis: AI analyzes patterns every 6 hours
• Working memory: Like human short-term memory for immediate access
• Performance: Minimal token usage, fast response times

Auto Ingest Mode

memori = Memori(auto_ingest=True)

• Dynamic search: Analyzes each query for relevant memories
• Full database search: Searches entire memory database
• Context-aware: Injects 3-5 most relevant memories per call
• Performance: Higher token usage, intelligent context

Manual Memory Operations

Record Conversations

# Manual conversation recording
chat_id = memori.record_conversation(
    user_input="I'm learning machine learning",
    ai_output="Start with Python basics and scikit-learn...",
    model="gpt-4o-mini"
)

# Trigger conscious analysis manually
memori.trigger_conscious_analysis()

Configuration Options

Basic Configuration

memori = Memori(
    database_connect="sqlite:///memori.db",  # Database connection
    conscious_ingest=True,                   # Enable smart context injection
    auto_ingest=False,                       # Disable dynamic search
    namespace="default",                     # Memory namespace
    openai_api_key="sk-..."                 # OpenAI API key
)

Advanced Configuration

memori = Memori(
    database_connect="postgresql://user:pass@localhost/memori",
    template="basic",
    conscious_ingest=True,
    auto_ingest=True,                        # Enable both modes
    namespace="web_project",
    shared_memory=False,
    memory_filters={
        "importance_threshold": 0.4,
        "categories": ["fact", "preference", "skill"]
    },
    openai_api_key="sk-..."
)

Provider Configuration

from memori.core.providers import ProviderConfig

# Azure OpenAI
azure_provider = ProviderConfig.from_azure(
    api_key="your-azure-key",
    azure_endpoint="https://your-resource.openai.azure.com/",
    azure_deployment="gpt-4o",
    api_version="2024-12-01-preview"
)

memori = Memori(
    database_connect="sqlite:///azure_memory.db",
    provider_config=azure_provider,
    conscious_ingest=True
)

Memory Namespaces

Separate memories for different projects:

# Work project memory
work_memori = Memori(namespace="work_project")
work_memori.enable()

# Personal project memory
personal_memori = Memori(namespace="personal")
personal_memori.enable()

# Each maintains separate memory context

Integration Examples

OpenAI Direct

import openai

memori.enable()  # Records all OpenAI calls

client = openai.OpenAI()
response = client.chat.completions.create(...)
# Automatically recorded with context injection

Anthropic Direct

import anthropic

memori.enable()  # Records all Anthropic calls

client = anthropic.Anthropic()
response = client.messages.create(...)
# Automatically recorded with context injection

LiteLLM (Recommended)

from litellm import completion

memori.enable()  # Uses native LiteLLM callbacks

completion(model="gpt-4", messages=[...])
completion(model="claude-3", messages=[...])
completion(model="gemini-pro", messages=[...])
# All providers automatically supported

Memory Search Tools

Function Calling Integration

from memori import create_memory_tool

# Create search tool for AI agents
memory_tool = create_memory_tool(memori)

# Use in function calling frameworks
def search_memory(query: str) -> str:
    """Search agent's memory for past conversations"""
    result = memory_tool.execute(query=query)
    return str(result) if result else "No relevant memories found"

# Use with LLM function calling
response = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What did I say about testing?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "search_memory",
            "description": "Search memory for relevant past conversations",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"]
            }
        }
    }]
)

Direct Search

# Search by content
memories = memori.retrieve_context("machine learning", limit=5)

# Get all memories
all_memories = memori.get_memories(limit=10)

# Memory statistics
stats = memori.get_memory_stats()
print(f"Total conversations: {stats['chat_history_count']}")
print(f"Long-term memories: {stats['long_term_count']}")

Best Practices

1. Choose the Right Memory Mode

# For immediate context and essential info
memori = Memori(conscious_ingest=True, auto_ingest=False)

# For intelligent, context-aware conversations
memori = Memori(conscious_ingest=True, auto_ingest=True)

# For maximum control
memori = Memori(conscious_ingest=False, auto_ingest=False)

2. Use Namespaces for Organization

# Separate memories by project/context
work = Memori(namespace="work_project")
personal = Memori(namespace="personal_assistant")
research = Memori(namespace="research_project")

3. Configure for Your Use Case

# Performance-focused
memori = Memori(
    conscious_ingest=True,
    auto_ingest=False,  # Reduce token usage
    memory_filters={"importance_threshold": 0.5}
)

# Context-rich conversations
memori = Memori(
    conscious_ingest=True,
    auto_ingest=True,   # Enable dynamic search
    memory_filters={"importance_threshold": 0.3}
)

4. Use Configuration Files

from memori import ConfigManager

config = ConfigManager()
config.auto_load()  # Loads from memori.json, env vars

memori = Memori()  # Uses loaded config
memori.enable()

5. Monitor Memory Usage

stats = memori.get_memory_stats()
print(f"Conversations: {stats.get('chat_history_count', 0)}")
print(f"Short-term: {stats.get('short_term_count', 0)}")
print(f"Long-term: {stats.get('long_term_count', 0)}")

# Trigger cleanup if needed
if stats.get('short_term_count', 0) > 1000:
    memori.trigger_conscious_analysis()

Troubleshooting

Memory Not Recording

# Check if enabled
if not memori._enabled:
    memori.enable()

# Verify API key configuration
config_info = memori.memory_manager.get_config_info() if hasattr(memori, 'memory_manager') else {}
print(f"Configuration loaded: {config_info}")

# Check conscious ingestion
print(f"Conscious ingest: {memori.conscious_ingest}")
print(f"Auto ingest: {memori.auto_ingest}")

Context Not Injecting

# Ensure conscious_ingest is enabled
memori = Memori(conscious_ingest=True)

# Check for relevant memories
memories = memori.retrieve_context("your query", limit=3)
print(f"Found {len(memories)} relevant memories")

# Manually trigger conscious analysis
memori.trigger_conscious_analysis()

Performance Issues

# Check memory statistics
stats = memori.get_memory_stats()
print(f"Total memories: {stats.get('total_memories', 0)}")

# Optimize settings for performance
memori = Memori(
    conscious_ingest=True,
    auto_ingest=False,  # Disable if not needed
    memory_filters={"importance_threshold": 0.5}  # Higher threshold
)

Database Issues

# Test database connection
try:
    stats = memori.get_memory_stats()
    print("Database connection OK")
    print(f"Database URL: {memori.database_connect}")
except Exception as e:
    print(f"Database error: {e}")

# Check database path for SQLite
import os
if memori.database_connect.startswith("sqlite:///"):
    db_path = memori.database_connect.replace("sqlite:///", "")
    print(f"Database file exists: {os.path.exists(db_path)}")