memorybox 1.0.0

Official Python SDK for Memory Box - Universal AI Memory Management

Memory Box Python SDK

Official Python SDK for Memory Box - Universal AI Memory Management.

Installation

pip install memorybox

Quick Start

from memorybox import MemoryBox

# Initialize with your API key
mb = MemoryBox(api_key="mb_live_your_api_key_here")

# List all memories
memories = mb.memories.list()
for memory in memories:
    print(f"[{memory.platform}] {memory.content[:100]}...")

# Create a new memory
memory = mb.memories.create(
    content="Important insight about machine learning models",
    platform="custom",
    role="assistant",
    metadata={"tags": ["ml", "important"]}
)

# Search memories
results = mb.memories.search("machine learning")
for result in results:
    print(result.content)

Getting an API Key

1. Go to Memory Box
2. Log in to your account
3. Navigate to Settings → API Keys
4. Click Create New API Key
5. Copy your key (it won't be shown again!)

Features

List Memories

# Get all memories
memories = mb.memories.list()

# Filter by platform
chatgpt_memories = mb.memories.list(platform="chatgpt")

# Pagination
page1 = mb.memories.list(limit=50, offset=0)
page2 = mb.memories.list(limit=50, offset=50)

# Sort by oldest first
oldest = mb.memories.list(sort="oldest")

# Text search
results = mb.memories.list(search="python programming")

Get a Specific Memory

memory = mb.memories.get(
    message_id="abc123",
    platform="chatgpt"
)
print(memory.content)

Create Memories

# Simple creation
memory = mb.memories.create(
    content="AI models are improving rapidly",
    platform="api"  # or "custom", "sdk", etc.
)

# With all options
memory = mb.memories.create(
    content="Detailed conversation content...",
    platform="custom",
    role="assistant",  # or "user"
    thread_id="my-conversation-123",
    metadata={
        "tags": ["important", "ml"],
        "source": "research-notes"
    }
)

Update Memories

# Update content
memory = mb.memories.update(
    message_id="abc123",
    platform="chatgpt",
    content="Updated content here"
)

# Update metadata only
memory = mb.memories.update(
    message_id="abc123",
    platform="chatgpt",
    metadata={"reviewed": True}
)

Delete Memories

# Delete single memory
mb.memories.delete(message_id="abc123", platform="chatgpt")

# Bulk delete (up to 100 at once)
mb.memories.bulk_delete([
    {"message_id": "abc123", "platform": "chatgpt"},
    {"message_id": "def456", "platform": "claude"},
    {"message_id": "ghi789", "platform": "gemini"},
])

Search

The SDK supports three search modes:

1. Hybrid Search (Recommended)

Combines keyword matching and semantic similarity for best results:

results = mb.memories.search(
    query="machine learning best practices",
    top_k=10,
    mode="hybrid",  # default
    keyword_weight=0.3,
    semantic_weight=0.7
)

for memory in results:
    score = memory.metadata.get('_score', 0)
    print(f"[{score:.2f}] {memory.content[:80]}...")

2. Semantic Similarity Search

Find conceptually similar memories using TF-IDF based similarity:

# Using convenience method
results = mb.memories.search_by_similarity(
    query="how do neural networks learn from data",
    top_k=5,
    min_score=0.1  # optional minimum similarity threshold
)

# Or using search() with mode parameter
results = mb.memories.search(
    query="explain transformers in NLP",
    mode="semantic",
    top_k=10
)

3. Keyword Matching Search

Find memories with exact or partial keyword matches:

# Match ANY keyword (OR)
results = mb.memories.search_by_keywords(
    query="python async await",
    match_mode="any"
)

# Match ALL keywords (AND)
results = mb.memories.search_by_keywords(
    query="machine learning python",
    match_mode="all"
)

# Match EXACT phrase
results = mb.memories.search_by_keywords(
    query="gradient descent",
    match_mode="exact"
)

Search with Platform Filter

# Search only in ChatGPT memories
results = mb.memories.search(
    query="code review",
    platform="chatgpt",
    top_k=5
)

Working with Search Results

results = mb.memories.search("machine learning", top_k=10)

# Iterate results
for memory in results:
    print(memory.content)

# Get top N
top_3 = results.top(3)

# Access scores
scores = results.get_scores()

# Index access
first = results[0]

# Check metadata
print(f"Mode: {results.mode}")
print(f"Total: {results.total}")

Statistics

# Get memory statistics
stats = mb.get_stats()

print(f"Total memories: {stats.total_memories}")
print(f"By platform: {stats.by_platform}")
print(f"By role: {stats.by_role}")

# Quick count
total = mb.memories.count()
chatgpt_count = mb.memories.count(platform="chatgpt")

API Key Scopes

Memory Box supports two API key scopes:

Scope	Permissions
read_only	List, get, search memories
read_write	All read operations + create, update, delete

Error Handling

from memorybox import (
    MemoryBox,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
    PermissionError,
)

mb = MemoryBox(api_key="mb_live_...")

try:
    memory = mb.memories.get("nonexistent", platform="chatgpt")
except AuthenticationError:
    print("Invalid or expired API key")
except NotFoundError:
    print("Memory not found")
except PermissionError:
    print("API key doesn't have permission for this operation")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ValidationError as e:
    print(f"Invalid request: {e.message}")

Configuration

# Use development server
mb = MemoryBox(
    api_key="mb_test_...",
    base_url="http://localhost:5000"
)

# Custom timeout
mb = MemoryBox(
    api_key="mb_live_...",
    timeout=60  # seconds
)

Pagination

The SDK returns PaginatedResponse objects for list operations:

response = mb.memories.list(limit=50)

# Access memories
for memory in response:
    print(memory.content)

# Pagination info
print(f"Total: {response.pagination.total}")
print(f"Has more: {response.pagination.has_more}")

# Get all pages
all_memories = []
offset = 0
while True:
    response = mb.memories.list(limit=100, offset=offset)
    all_memories.extend(response.items)
    if not response.pagination.has_more:
        break
    offset += 100

Testing

Quick Test

# Install the SDK locally
cd Memory-Box-Website/memorybox-sdk
pip install -e .

# Run the test script (shows usage without API key)
python examples/test_search_features.py

# Run with your API key
$env:API_KEY = "mb_live_your_key_here"  # PowerShell
python examples/test_search_features.py

Unit Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_search.py -v

# Run with coverage
pytest tests/ --cov=memorybox --cov-report=html

Live Integration Test

from memorybox import MemoryBox

# Initialize with your API key
mb = MemoryBox(api_key="mb_live_your_key")

# Check connection
print(mb.health_check())

# Get your stats
stats = mb.get_stats()
print(f"Total memories: {stats.total_memories}")

# Test semantic search
results = mb.memories.search_by_similarity("test query", top_k=3)
print(f"Found {len(results)} similar memories")

# Test keyword search  
results = mb.memories.search_by_keywords("test", match_mode="any")
print(f"Found {len(results)} keyword matches")

Development

# Clone the repository
git clone https://github.com/ChonghaoSu/Memory-Box-Website.git
cd Memory-Box-Website/memorybox-sdk

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

# Run tests
pytest

# Format code
black src/
isort src/

Support

• Documentation: memorybox.hawltechs.com/docs
• Issues: GitHub Issues
• Email: [e-mail]

License

MIT License - see LICENSE for details.