peargent.

Use Metadata for Search and Filtering

# Tag threads with searchable metadata
history.create_thread(metadata={
    "user_id": "alice",
    "topic": "technical_support",
    "priority": "high",
    "created_by": "web_app",
    "tags": ["billing", "bug_report"]
})

# Later: Find threads by metadata
all_threads = history.list_threads()
high_priority = []
for thread_id in all_threads:
    thread = history.get_thread(thread_id)
    if thread.metadata.get("priority") == "high":
        high_priority.append(thread_id)

Use Message Metadata for Tracking

history.add_user_message(
    "Process this document",
    metadata={
        "source": "api",
        "user_ip": "192.168.1.1",
        "request_id": "req_123",
        "timestamp_ms": 1234567890
    }
)

history.add_assistant_message(
    "Document processed successfully",
    agent="DocumentProcessor",
    metadata={
        "model": "gpt-4o",
        "tokens_used": 1250,
        "latency_ms": 2340,
        "cost_usd": 0.025
    }
)

Implement Cleanup Policies

from datetime import datetime, timedelta

def cleanup_old_threads(history, days=30):
    """Delete threads older than specified days."""
    cutoff = datetime.now() - timedelta(days=days)

    all_threads = history.list_threads()
    deleted = 0

    for thread_id in all_threads:
        thread = history.get_thread(thread_id)
        if thread.created_at < cutoff:
            history.delete_thread(thread_id)
            deleted += 1

    return deleted

# Run cleanup
deleted_count = cleanup_old_threads(history, days=90)
print(f"Deleted {deleted_count} old threads")

Export Conversations

import json

def export_thread(history, thread_id, filename):
    """Export thread to JSON file."""
    thread = history.get_thread(thread_id)
    if not thread:
        return False

    with open(filename, 'w') as f:
        json.dump(thread.to_dict(), f, indent=2)

    return True

# Export specific conversation
export_thread(history, thread_id, "conversation_export.json")

# Import conversation
def import_thread(history, filename):
    """Import thread from JSON file."""
    from peargent.storage import Thread

    with open(filename, 'r') as f:
        data = json.load(f)

    thread = Thread.from_dict(data)

    # Create thread in history
    new_thread_id = history.create_thread(metadata=thread.metadata)

    # Add all messages
    for msg in thread.messages:
        if msg.role == "user":
            history.add_user_message(msg.content, metadata=msg.metadata)
        elif msg.role == "assistant":
            history.add_assistant_message(msg.content, agent=msg.agent, metadata=msg.metadata)
        elif msg.role == "tool":
            history.add_tool_message(msg.tool_call, agent=msg.agent, metadata=msg.metadata)

    return new_thread_id

Context Window Monitoring

def should_manage_context(history, threshold=20):
    """Check if context management is needed."""
    count = history.get_message_count()

    if count > threshold:
        print(f"⚠️ Context window full: {count}/{threshold} messages")
        return True
    else:
        print(f"✓ Context OK: {count}/{threshold} messages")
        return False

# Monitor before agent runs
if should_manage_context(history, threshold=25):
    history.manage_context_window(
        model=groq("llama-3.1-8b-instant"),
        max_messages=25,
        strategy="smart"
    )