DOCSEARCHbyAlgolia
Submit Docs

Memobase Documentation

repository·main·Indexed 25 days ago

https://github.com/memodb-io/memobase

A user profile-based long-term memory system for LLM applications that allows AI agents to maintain structured profiles and event timelines. It features a Python client, an MCP server (memobase-mcp v0.1.0), and optimizations for latency and cost through a buffering system and dynamic profiling. The system supports integration with LiveKit for voice agents, local LLMs via Ollama, and provides tools for memory extraction and benchmarking against other backends like Mem0, Zep, and LangMem.

Tokens
44.1K
Snippets
118
Records
302
Agent score
82%

What's inside Memobase

  1. Overview of Memobase API categories

    main

    The Memobase API is organized into three primary functional categories:

    1. User APIs: For managing user entities (creating, updating, and deleting users).
    2. Data APIs: For handling raw data operations (inserting, getting, deleting, or listing blobs).
    3. Profile APIs: For managing user profiles (retrieving profiles, deleting specific profiles, and customizing profile generation settings).

  2. Overview of Memobase Backend API

    main
    Memobase is a user memory system designed for LLM applications. It provides a FastAPI-based server that manages user profiles, memories, and various types of data blobs. The system is built to support long-term user profile storage, automatic memory merging, and token-aware content management.

  3. Understand Memobase core features and architecture

    main

    Memobase is an AI-powered backend service designed to manage dynamic user profiles for AI applications. It automates the process of building structured user profiles by analyzing interactions.

    Key architectural concepts include:

    • User Profiles as Memory: Profiles are organized into a structured topic/subtopic format (e.g., interests/movies), allowing you to define custom memory slots for any data point.
    • Data Blobs: User data is stored in flexible "blobs" that can be inserted, retrieved, or deleted.
    • Buffering System: Recent data is held in a temporary buffer before being processed and integrated into the long-term user profile. This buffer can be flushed automatically or manually to evolve the profile.

  4. Compare Memobase vs Mem0 performance

    main

    Based on experiments using 900 turns of chat from the ShareGPT dataset, Memobase demonstrates significant advantages in cost and speed compared to Mem0:

    MetricMemobaseMem0
    Estimated LLM Cost~$0.042~$0.24
    Insertion Time270-300 seconds~1,683 seconds

    Key Architectural Differences

    • Buffering: Mem0 uses 'hot-path updates' where each Memory.add triggers a memory flush, leading to more LLM calls. Memobase includes a buffer zone to handle insertions automatically, reducing LLM overhead.
    • Retrieval Method: Mem0 computes and retrieves embeddings for every insertion. Memobase uses dynamic profiling to generate primary and secondary indices for users, retrieving memories via SQL queries instead of embeddings for user memory.

  5. Understand Memobase Data Processing

    main

    Memobase uses a buffering system for efficiency:

    • Data Blobs: User data is stored in flexible 'blobs'.
    • Buffering: Recent data is held in a temporary buffer before being processed and integrated into the long-term profile. This allows for batch processing, which reduces AI analysis costs.
    • Automatic Cleanup: By default, Memobase processes and removes raw memory blobs after generating profiles to ensure privacy and efficient storage. This behavior can be customized via configuration.

  7. Configure and Use Event Tags

    main

    Event tags allow for automatic semantic categorization of user events (e.g., emotion, life_goals).

    Configuration

    Define tags in config.yaml using name and description. The description is critical for the AI to know when to apply the tag.

    event_tags:
  - name: "emotion"
    description: "Records the user's current emotional state."
  - name: "romance"
    description: "Tracks any mention of romantic relationships or feelings."

    Retrieving and Searching Tags

    Tags are returned within the event_data.event_tags field of an event object. You can also search for events by specific tags using user.search_event(tags=[...]).

    from memobase import MemoBaseClient

client = MemoBaseClient(project_url='YOUR_PROJECT_URL', api_key='YOUR_API_KEY')
user = client.get_user('some_user_id')

# Retrieve and print tags from event history
events = user.event()
for event in events:
    print(event.event_data.event_tags)

# Search for events with specific tags
events = user.search_event(tags=["emotion"])
print(events)

  9. Run memory extraction for multiple chat sessions

    main

    Use the extract.py script to process chat history and extract user profiles. This requires Python >= 3.11 and a running Memobase Server.

    Prerequisites:

    • Python >= 3.11
    • Memobase Server must be running.

    Steps:

    1. Install dependencies: pip install -r requirements.txt
    2. Run the extraction for a specific user: python extract.py --user <USER>

    The script will automatically output the updated user profile after processing each conversation round.

    # Python >= 3.11
pip install -r requirements.txt
python extract.py --user <USER>

  10. Integrate Memobase with the OpenAI API

    main

    You can add long-term memory to your OpenAI chat completions by patching the official OpenAI SDK using the openai_memory function. This allows you to inject user context into prompts and save interactions to Memobase automatically by simply providing a user_id in your API calls.

    Setup

    1. Install the required SDKs:
    pip install memobase openai
    1. Initialize both clients and apply the patch:
    from openai import OpenAI
from memobase import MemoBaseClient
from memobase.patch.openai import openai_memory

client = OpenAI()
mb_client = MemoBaseClient(
    project_url=YOUR_PROJECT_URL,
    api_key=YOUR_API_KEY,
)

# Apply the memory patch
client = openai_memory(client, mb_client)

    Usage

    To enable memory, pass a user_id to the chat.completions.create method. If user_id is omitted, the client behaves like the standard OpenAI client.

    client.chat.completions.create(
    messages=[
        {"role": "user", "content": "My name is Gus"},
    ],
    model="gpt-4o",
    user_id="test_user_123",
)
    from openai import OpenAI
from memobase import MemoBaseClient
from memobase.patch.openai import openai_memory

client = OpenAI()
mb_client = MemoBaseClient(
    project_url=YOUR_PROJECT_URL,
    api_key=YOUR_API_KEY,
)

client = openai_memory(client, mb_client)

client.chat.completions.create(
    messages=[
        {"role": "user", "content": "My name is Gus"},
    ],
    model="gpt-4o",
    user_id="test_user_123",
)

  11. Configure Memobase Backend with config.yaml

    main

    When developing Memobase locally, you can use a config.yaml file to configure the Memobase Backend. This file serves as the central source for storage, performance, timezone, LLM, embedding, profile, and summary settings.

    # Storage and Performance
persistent_chat_blobs: false
buffer_flush_interval: 3600
max_chat_blob_buffer_token_size: 1024
max_profile_subtopics: 15
max_pre_profile_token_size: 128
cache_user_profiles_ttl: 1200

# Timezone
use_timezone: "UTC"

# LLM Configuration
language: "en"
lm_style: "openai"
lm_base_url: "https://api.openai.com/v1/"
lm_api_key: "YOUR-KEY"
best_llm_model: "gpt-4o-mini"
summary_llm_model: null

# Embedding Configuration
enable_event_embedding: true
embedding_provider: "openai"
embedding_api_key: null
embedding_base_url: null
embedding_dim: 1536
embedding_model: "text-embedding-3-small"
embedding_max_token_size: 8192

# Profile Configuration
additional_user_profiles:
  - topic: "gaming"
    sub_topics:
      - "Soul-Like"
      - "RPG"
profile_strict_mode: false
profile_validate_mode: true

# Summary Configuration
minimum_chats_token_size_for_event_summary: 256

  12. Optimize Memobase performance and cost

    main

    Memobase achieves high performance and cost-efficiency through three primary mechanisms:

    1. Fast Query Performance: Queries return pre-compiled user profiles, avoiding the latency of on-the-fly analysis.
    2. Controllable Costs: You can manage expenses by configuring the number of profile slots and the maximum token size for each slot.
    3. Efficient Data Insertion: New data is added to a buffer and processed in batches, which amortizes the cost of AI analysis and ensures fast, inexpensive insertions.

    To manage these aspects, refer to the documentation for profile slot design, token limits, and buffer configuration.