This guide provides tips for effectively using Memobase in your applications.

Configuring User Memory

You can define the structure of user profiles by configuring topics and sub-topics in your config.yaml file. This tells Memobase what kind of information to track.

- topic: "Gaming"
  description: "Tracks the user's gaming preferences and achievements."
  sub_topics:
      - name: "FPS"
      - name: "LOL"
- topic: "Professional"
  description: "Tracks the user's professional background."
  sub_topics:
    - name: "Industry"
    - name: "Role"

Memobase uses this configuration to generate structured user profiles. Learn more about customization at Profile Configuration.

Integrating Memory into Prompts

There are two primary ways to retrieve and use a user’s memory.

Method 1: Profile API (Manual Assembly)

The Profile API returns a structured JSON object containing the user’s profile data. You are responsible for formatting this JSON into a string and inserting it into your prompt.

Key Considerations:

  • Context Length: Control the token count of the memory context to manage cost and performance. Use max_token_size to set a hard limit and max_subtopic_size to limit the number of sub-topics per topic.
  • Topic Filtering: Use only_topics to retrieve specific profile sections or prefer_topics to prioritize the most important information.

Method 2: Context API (Automated Assembly)

The Context API returns a pre-formatted string containing both the user’s profile and recent events, ready to be injected directly into your system prompt. It uses a template like this:

<memory>
# User Profile:
{profile}

# Recent Events:
{event}
</memory>
Use the information in the <memory> tag when relevant.

Flushing the Memory Buffer

Memobase uses a buffer to collect user interactions. A flush operation processes this buffer and updates the long-term memory. Flushing occurs automatically when:

  • The buffer exceeds a certain size.
  • The buffer has been idle for a set period.

You can also trigger it manually with the flush API. It is best practice to call flush at the end of a user session or conversation.

User ID Management

A single user in your application can correspond to multiple Memobase users. This is useful for creating segmented memories.

  • Example: AI Role-Playing: If a user interacts with multiple AI agents (e.g., a history tutor and a creative writer), you can create a separate Memobase user for each agent. This keeps the memories for each role distinct.

We recommend designing your system with a one-to-many mapping between your application’s user ID and Memobase user IDs.

Enriching Conversation Data

You can add metadata to the messages you insert to provide more context for memory extraction.

  • Speaker Alias: Use alias to specify the name of the AI assistant in the conversation.
    {
        "role": "assistant",
        "content": "Hi, nice to meet you, Gus!",
        "alias": "HerAI"
    }
    
  • Timestamps: Provide a created_at timestamp for each message so Memobase can build a timeline of events.
    {
        "role": "user",
        "content": "Hello, I'm Gus",
        "created_at": "2025-01-14T10:00:00Z"
    }
    

See a full implementation in our demo script.