Memphora Python SDK

Persistent memory layer for AI agents. Store, search, and retrieve memories with semantic understanding.

Installation

pip install memphora

Quick Start

from memphora import Memphora

# Initialize
memory = Memphora(
    user_id="user123",        # Unique identifier for this user (Admin can track data from dashboard)
    api_key="your_api_key"    # Required: Get from https://memphora.ai/dashboard
)

# Store a memory
memory.store("I love playing basketball on weekends")

# Search memories
results = memory.search("What sports do I like?")
print(results)

# Get context for a conversation
context = memory.get_context("Tell me about my hobbies")

Features

• 🧠 Semantic Search - Find memories by meaning, not just keywords
• 🔄 Auto-consolidation - Automatically merges duplicate memories
• 📊 Graph Relationships - Link related memories together
• 🤖 Multi-Agent Support - Separate memory spaces for different agents
• 👥 Group Memories - Shared memories for teams
• 📈 Analytics - Track memory growth and usage

API Reference

Initialize

memory = Memphora(
    user_id="user123",        # Unique identifier for this user (Admin can track data from dashboard)
    api_key="your_api_key"    # Required: API key from https://memphora.ai/dashboard
)

Core Methods

store(content: str, metadata: dict = None) -> dict

Store a new memory.

mem = memory.store("I work as a software engineer", {
    "category": "work",
    "importance": "high"
})

search(query: str, limit: int = 10, **options) -> list

Search memories semantically with optional external reranking.

# Basic search
results = memory.search("What is my job?", limit=5)

# Search with Cohere reranking for better relevance
reranked_results = memory.search("headphone recommendations", limit=10,
    rerank=True,
    rerank_provider="cohere",  # or "jina" or "auto"
    cohere_api_key="your-cohere-api-key"  # Get from https://dashboard.cohere.com/api-keys
)

# Search with Jina AI reranking (multilingual support)
jina_results = memory.search("recomendaciones de auriculares", limit=10,
    rerank=True,
    rerank_provider="jina",
    jina_api_key="your-jina-api-key"  # Get from https://jina.ai/
)

get_context(query: str, limit: int = 5) -> str

Get formatted context for AI prompts.

context = memory.get_context("Tell me about myself")
# Returns: "Relevant context from past conversations:\n- I work as a software engineer\n- ..."

Advanced Methods

store_conversation(user_message: str, ai_response: str) -> None

Store a conversation and extract memories. Returns the extracted memories.

memory.store_conversation(
    "What's my favorite color?",
    "Based on your memories, your favorite color is blue."
)

list_memories(limit: int = 100) -> list

List all memories for the user.

all_memories = memory.list_memories(limit=100)

update_memory(memory_id: str, content: str = None, metadata: dict = None) -> dict

Update an existing memory.

updated = memory.update_memory(memory_id, "Updated content", {"category": "work"})

delete_memory(memory_id: str) -> bool

Delete a memory.

memory.delete_memory(memory_id)

get_memory(memory_id: str) -> dict

Get a specific memory by ID.

mem = memory.get_memory(memory_id)
print(mem["content"])

clear() -> bool

Delete all memories for this user. Warning: This action is irreversible.

memory.clear()

Advanced Search

# Advanced search with filters and options
results = memory.search_advanced("query",
    limit=10,
    filters={"category": "work"},
    min_score=0.7,
    sort_by="relevance"
)

# Optimized search for better performance
optimized = memory.search_optimized("query",
    max_tokens=2000,
    max_memories=20,
    use_compression=True
)

Batch Operations

# Store multiple memories at once
memories = memory.batch_store([
    {"content": "Memory 1", "metadata": {"category": "work"}},
    {"content": "Memory 2", "metadata": {"category": "personal"}}
])

# Merge multiple memories
merged = memory.merge([memory_id1, memory_id2], "combine")

Analytics

# Get user statistics
stats = memory.get_statistics()
print(stats)
# {"totalMemories": 42, "avgMemoryLength": 85, ...}

Graph Features

# Get memory context with related memories
context = memory.get_context_for_memory(memory_id, depth=2)

# Get memories related to a specific memory
related = memory.get_related_memories(memory_id, limit=10)

# Find contradictions
contradictions = memory.find_contradictions(memory_id, threshold=0.7)

# Link two memories in the graph
memory.link(
    memory_id,
    target_id,
    "related"  # or "contradicts", "supports", "extends"
)

# Find shortest path between two memories
path = memory.find_path(source_id, target_id)
print(path["distance"])  # Number of steps

Context Methods

# Get optimized context (26% better accuracy, 91% faster)
optimized_context = memory.get_optimized_context(
    "user preferences",
    max_tokens=2000,
    max_memories=20,
    use_compression=True,
    use_cache=True
)

# Get enhanced context (35%+ accuracy improvement)
enhanced_context = memory.get_enhanced_context(
    "programming languages",
    max_tokens=1500,
    max_memories=15,
    use_compression=True
)

Version Control

# Get all versions of a memory
versions = memory.get_versions(memory_id, limit=50)

# Compare two versions
comparison = memory.compare_versions(version_id1, version_id2)
print(comparison["changes"])
print(comparison["similarity"])

# Rollback to a specific version
memory.rollback(memory_id, target_version)

Conversation Management

# Record a full conversation
conversation = [
    {"role": "user", "content": "I need help with Python"},
    {"role": "assistant", "content": "I'd be happy to help!"}
]
recorded = memory.record_conversation(conversation, "web_chat", {
    "session_id": "sess_123"
})

# Get all conversations
conversations = memory.get_conversations("web_chat", limit=50)

# Get a specific conversation by ID
conv = memory.get_conversation(conversation_id)

# Get rolling summary of all conversations
summary = memory.get_summary()
print(summary["total_conversations"])
print(summary["topics"])

Multi-Agent Support

# Store a memory for a specific agent
memory.store_agent_memory(
    "agent_123",
    "User prefers Python for backend development",
    "run_001",  # optional run_id
    {"category": "preference"}
)

# Search memories for a specific agent
agent_memories = memory.search_agent_memories(
    "agent_123",
    "What does the user prefer?",
    "run_001",  # optional run_id
    limit=10
)

# Get all memories for a specific agent
all_agent_memories = memory.get_agent_memories("agent_123", limit=100)

Group/Collaborative Features

# Store a shared memory for a group
memory.store_group_memory(
    "team_alpha",
    "Team decided to use React for the frontend",
    {"priority": "high"}
)

# Search memories for a group
group_memories = memory.search_group_memories(
    "team_alpha",
    "What framework did we choose?",
    limit=10
)

# Get context for a group
group_context = memory.get_group_context("team_alpha", limit=50)

Analytics

# Get user statistics
stats = memory.get_statistics()
print(stats)
# {"totalMemories": 42, "avgMemoryLength": 85, ...}

# Get user's memory statistics and insights
analytics = memory.get_user_analytics()
print(analytics)

# Track memory growth over time
growth = memory.get_memory_growth(days=30)  # last 30 days
print(growth)

Image Operations

# Store an image memory
image_mem = memory.store_image(
    image_url="https://example.com/photo.jpg",
    description="A photo of the Golden Gate Bridge",
    metadata={"location": "San Francisco", "type": "landmark"}
)

# Search image memories
image_results = memory.search_images("bridge", limit=5)

# Upload an image from file
with open("product_photo.jpg", "rb") as f:
    image_data = f.read()
uploaded = memory.upload_image(
    image_data,
    "product_photo.jpg",
    {"category": "product", "product_id": "prod_123"}
)

Export & Import

# Export all memories
export_data = memory.export("json")
# or
csv_data = memory.export("csv")

# Import memories
memory.import_memories(export_data["data"], "json")

Text Processing

# Make text more concise
concise_result = memory.concise("This is a very long text that needs to be made more concise...")
print(concise_result["concise_text"])

Health Check

# Check API health
health = memory.health()
print(health["status"])

Type Hints

Full type hint support included.

from memphora import Memphora
from typing import List, Dict
import os

memory: Memphora = Memphora(
    user_id="user123",                    # Unique identifier for this user (Admin can track data from dashboard)
    api_key=os.environ["MEMPHORA_API_KEY"]  # Required: API key from dashboard
)

results: List[Dict] = memory.search("query")

Error Handling

try:
    memory.store("My memory")
except Exception as e:
    if "401" in str(e):
        print("Invalid API key")
    elif "429" in str(e):
        print("Rate limit exceeded")
    else:
        print(f"Error: {e}")

Examples

Chatbot with Memory

from memphora import Memphora
import os

memory = Memphora(
    user_id="user123",                    # Unique identifier for this user (Admin can track data from dashboard)
    api_key=os.environ["MEMPHORA_API_KEY"]  # Required: Get from dashboard
)

def chat(user_message: str) -> str:
    # Get relevant context
    context = memory.get_context(user_message)
    
    # Generate AI response with context
    ai_response = generate_ai_response(user_message, context)
    
    # Store the conversation
    memory.store_conversation(user_message, ai_response)
    
    return ai_response

Multi-Agent System

memory = Memphora(
    user_id="user123",
    api_key="your_api_key"
)

# Store memories for different agents
memory.store_agent_memory("coder", "User prefers Python", "run_001")
memory.store_agent_memory("writer", "User likes technical writing", "run_001")

# Search memories for a specific agent
coder_memories = memory.search_agent_memories("coder", "What does the user prefer?")

# Get all memories for an agent
all_coder_memories = memory.get_agent_memories("coder", limit=100)

Group Collaboration

memory = Memphora(
    user_id="user123",
    api_key="your_api_key"
)

# Store shared memories for a team
memory.store_group_memory("team_alpha", "Team decided to use React", {
    "priority": "high",
    "decision_date": "2024-01-15"
})

# Search group memories
team_memories = memory.search_group_memories("team_alpha", "What framework?")

# Get group context
team_context = memory.get_group_context("team_alpha", limit=50)

Memory Linking and Path Finding

memory = Memphora(
    user_id="user123",
    api_key="your_api_key"
)

# Store related memories
mem1 = memory.store("User works at Google")
mem2 = memory.store("User is a software engineer")
mem3 = memory.store("User lives in San Francisco")

# Link memories together
memory.link(mem1["id"], mem2["id"], "related")
memory.link(mem1["id"], mem3["id"], "related")

# Get related memories
related = memory.get_related_memories(mem1["id"], limit=10)

# Find path between memories
path = memory.find_path(mem1["id"], mem3["id"])
print(f"Path distance: {path['distance']} steps")

Version Control and Rollback

memory = Memphora(
    user_id="user123",
    api_key="your_api_key"
)

# Store and update a memory multiple times
mem = memory.store("User works at Microsoft")
memory.update_memory(mem["id"], "User works at Google")
memory.update_memory(mem["id"], "User works at Meta")

# Get all versions
versions = memory.get_versions(mem["id"], limit=10)
for v in versions:
    print(f"Version {v['version']}: {v['content']}")

# Compare two versions
comparison = memory.compare_versions(versions[0]["id"], versions[1]["id"])
print("Changes:", comparison["changes"])
print("Similarity:", comparison["similarity"])

# Rollback to a previous version
memory.rollback(mem["id"], 1)

Using Optimized Context

memory = Memphora(
    user_id="user123",
    api_key="your_api_key"
)

# Get optimized context (best for production)
optimized_context = memory.get_optimized_context(
    "user preferences",
    max_tokens=2000,
    max_memories=20,
    use_compression=True,
    use_cache=True
)

# Use in your AI prompt
prompt = f"""Context about user:
{optimized_context}

User query: What are my preferences?
Assistant:"""

response = your_ai_model(prompt)

Decorator Pattern

from memphora import Memphora

memory = Memphora(
    user_id="user123",
    api_key="your_api_key"
)

@memory.remember
def chat(user_message: str, memory_context: str = "") -> str:
    # memory_context is automatically injected with relevant memories
    ai_response = generate_response(user_message, memory_context)
    return ai_response

# The decorator will:
# 1. Search for relevant memories
# 2. Add them to kwargs as 'memory_context'
# 3. Store the conversation after response

License

MIT

Links

• Documentation
• Dashboard
• GitHub
• PyPI

Support

• Email: info@memphora.ai
• Issues