> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recallrai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memories

> Understanding memories - the extracted facts and knowledge from conversations

## What are Memories?

Memories are the facts, preferences, and knowledge that Recallr automatically extracts from your conversations. Think of them as the key takeaways from each session - the important information worth remembering for future interactions.

## Memory Categories

Memory categories help you organize and filter memories based on their type or domain. Categories make it easier to retrieve relevant memories and maintain clean, structured knowledge about your users.

### Managing Categories

Categories are configured through the [Recallr Dashboard](https://app.recallrai.com) for each project. You can create custom categories that match your application's needs.

<Steps>
  <Step title="Access the Dashboard">
    Navigate to your project settings in the Recallr Dashboard.
  </Step>

  <Step title="Create a Category">
    Add a new category with a descriptive name and optional description.

    <ParamField path="name" type="string" required>
      Use descriptive, lowercase names with underscores (e.g., `food_preferences`, `medical_history`).
    </ParamField>

    <ParamField path="description" type="string">
      Optional description explaining what this category contains.
    </ParamField>
  </Step>

  <Step title="Use Categories">
    Once created, Recallr will automatically assign memories to appropriate categories during extraction, and you can filter memories by category when retrieving them.
  </Step>
</Steps>

<Tip>
  Create categories that align with your application's domain. For a healthcare app, you might use categories like `medical_history`, `medications`, and `allergies`. For an e-commerce app, consider `product_preferences`, `shopping_habits`, and `size_information`.
</Tip>

<Warning>
  **Important category considerations:**

  * Deleting a category does not delete memories - existing memories will remain in the system but will no longer be associated with that category
  * Categories are not retroactive - only new memories extracted after a category is created will be assigned to it. Existing memories will not be automatically recategorized
</Warning>

## Customizing Memory Extraction

Recallr provides powerful customization options to tailor the memory extraction process to your specific needs. Configure these settings through the **Dashboard** to control how memories are generated from conversations.

### Generation Preferences

<AccordionGroup>
  <Accordion title="Inclusion Instructions">
    Custom instructions to guide what aspects should be included in generated memories.

    <ParamField body="inclusion_instructions" type="array of strings">
      List of specific instructions to emphasize certain aspects during memory extraction.

      <Expandable title="Example">
        ```json theme={null}
        [
          "Always capture specific product names and brands mentioned",
          "Include temporal context for events (when something happened)",
          "Extract numerical measurements and quantities precisely"
        ]
        ```
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Positive Examples">
    Examples of well-formatted, high-quality memories to guide the extraction model.

    <ParamField body="positive_examples" type="array of strings">
      Short examples demonstrating the desired memory format and content.

      <Expandable title="Example">
        ```json theme={null}
        [
          "User prefers Nike running shoes in size 10",
          "User's birthday is March 15, 1990",
          "User works as a software engineer at TechCorp since 2020"
        ]
        ```
      </Expandable>
    </ParamField>

    <Tip>
      Provide 3-5 positive examples that represent the ideal structure and detail level for your use case.
    </Tip>
  </Accordion>

  <Accordion title="Exclusion Instructions">
    Instructions to prevent certain types of information from being stored as memories.

    <ParamField body="exclusion_instructions" type="array of strings">
      Specific guidelines for what to avoid capturing as memories.

      <Expandable title="Example">
        ```json theme={null}
        [
          "Do not store temporary session-specific information",
          "Exclude casual greetings and pleasantries",
          "Ignore hypothetical scenarios or 'what-if' discussions"
        ]
        ```
      </Expandable>
    </ParamField>

    <Warning>
      Use exclusion instructions to avoid storing sensitive information, temporary data, or noise that doesn't provide long-term value.
    </Warning>
  </Accordion>

  <Accordion title="Negative Examples">
    Examples of poor-quality memories that should be avoided.

    <ParamField body="negative_examples" type="array of strings">
      Short examples showing what NOT to extract as memories.

      <Expandable title="Example">
        ```json theme={null}
        [
          "User said hello",
          "The weather was discussed",
          "User asked a question"
        ]
        ```
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="False Positive Examples">
    Memories that were incorrectly extracted when they shouldn't have been (actual negative, predicted positive).

    <ParamField body="false_positive_examples" type="array of strings">
      Examples where the system incorrectly created a memory. Use these to fine-tune extraction precision.

      <Expandable title="Use Case">
        Help the model learn from past mistakes by showing examples of information that was extracted but shouldn't have been.
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="False Negative Examples">
    Important information that was missed during extraction (actual positive, predicted negative).

    <ParamField body="false_negative_examples" type="array of strings">
      Examples where the system failed to create a memory that should have been created. Use these to improve extraction recall.

      <Expandable title="Use Case">
        Teach the model to catch important information it previously missed.
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Similarity Check Configuration">
    Control how Recallr checks for redundant memories during generation.

    <ParamField body="top_k_symantic_similarity_check" type="integer" required>
      Number of existing memories to check for similarity before creating a new memory. Range: 10-50.

      Higher values provide more thorough redundancy checking but increase processing time.
    </ParamField>

    <Info>
      Recallr uses LLM-based similarity checking to avoid creating duplicate or highly similar memories. This parameter controls how many existing memories are evaluated for each new memory candidate.
    </Info>
  </Accordion>

  <Accordion title="Merge Conflict Handling">
    Configure whether the system should raise merge conflicts for ambiguous situations.

    <ParamField body="raise_merge_conflict" type="boolean" required>
      When `true`, Recallr will create merge conflicts when it detects potentially contradictory or ambiguous information. When `false`, it will automatically resolve conflicts using its best judgment.
    </ParamField>

    <Check>
      Enable merge conflicts for critical applications where you need human review of ambiguous updates. Disable for faster processing when automated resolution is acceptable.
    </Check>
  </Accordion>
</AccordionGroup>

## Customizing Memory Recall

The recall system determines which memories are retrieved when you call `getContext()`. Customize recall behavior through the **Dashboard** to optimize for your specific use case.

### Recall Strategies

Recallr offers three recall strategies with different performance characteristics:

<CardGroup cols={3}>
  <Card title="Low Latency" icon="bolt">
    Fastest retrieval with basic semantic search. Best for real-time applications where speed is critical.
  </Card>

  <Card title="Balanced" icon="scale-balanced">
    Combines multiple retrieval techniques for better accuracy with reasonable performance. **Recommended for most use cases.**
  </Card>

  <Card title="Agentic" icon="magnifying-glass">
    Most comprehensive search using subqueries, keywords, and semantic similarity. Best when accuracy is paramount.
  </Card>
</CardGroup>

### Recall Preferences

Configure these settings for **Balanced** and **Agentic** recall strategies:

<AccordionGroup>
  <Accordion title="Custom Instructions">
    Guide the subquery and keyword generation process with specific instructions.

    <ParamField body="custom_instructions" type="array of strings">
      Instructions to help generate better search queries and keywords from user messages.

      <Expandable title="Example">
        ```json theme={null}
        [
          "Focus on extracting the user's intent and goal",
          "Include domain-specific terminology in keywords",
          "Consider temporal context when generating subqueries"
        ]
        ```
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Subquery Configuration">
    Control how subquery-based recall contributes to memory retrieval.

    <ParamField body="subqueries_candidate_memories_weight" type="float" required>
      Weight for memories retrieved via subquery matching. Range: 0.0-1.0.

      Higher values give more importance to memories found through generated subqueries.
    </ParamField>

    <ParamField body="example_subqueries" type="array of strings">
      Example subqueries to guide the generation process.

      <Expandable title="Example">
        ```json theme={null}
        [
          "What are the user's dietary restrictions?",
          "Has the user mentioned any health conditions?",
          "What products has the user purchased before?"
        ]
        ```
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Keyword Configuration">
    Control how keyword-based recall contributes to memory retrieval.

    <ParamField body="keywords_candidate_memories_weight" type="float" required>
      Weight for memories retrieved via keyword matching. Range: 0.0-1.0.

      Higher values give more importance to memories found through keyword extraction.
    </ParamField>

    <ParamField body="example_keywords" type="array of strings">
      Example keywords to guide the extraction process.

      <Expandable title="Example">
        ```json theme={null}
        [
          "allergy, peanuts, shellfish",
          "preference, vegetarian, organic",
          "medical, diabetes, medication"
        ]
        ```
      </Expandable>
    </ParamField>
  </Accordion>

  <Accordion title="Summary Search Examples">
    Guide how the system generates questions for searching session summaries.

    <ParamField body="example_summary_search_questions" type="array of strings">
      Example questions that help retrieve relevant session summaries.

      <Expandable title="Example">
        ```json theme={null}
        [
          "What did the user say about their preferences?",
          "What problems or issues has the user mentioned?",
          "What are the user's goals and objectives?"
        ]
        ```
      </Expandable>
    </ParamField>
  </Accordion>
</AccordionGroup>

<Tip>
  Fine-tune recall weights based on your testing. Start with equal weights (0.5 for both subqueries and keywords) and adjust based on which retrieval method performs better for your use case.
</Tip>

## Memory Versioning

Recallr maintains a complete version history for each memory, allowing you to track how information evolves over time and understand why changes occurred.

### How Versioning Works

When information about a user is updated, Recallr doesn't simply overwrite the old memory. Instead, it creates a new version and preserves the previous one with metadata explaining why it changed.

<Steps>
  <Step title="Initial Memory Created">
    First version is created during session processing.

    ```
    Version 1: "User prefers contact by email"
    Created: 2024-01-15 10:00:00
    Status: Current
    ```
  </Step>

  <Step title="New Information Emerges">
    During a later session, contradictory or updated information appears.

    ```
    User: "Actually, I prefer text messages now instead of email"
    ```
  </Step>

  <Step title="New Version Created">
    Recallr creates version 2 and expires version 1.

    ```
    Version 1: "User prefers contact by email"
    Created: 2024-01-15 10:00:00
    Expired: 2024-02-20 14:30:00
    Expiration Reason: "updated"

    Version 2: "User prefers contact by text message"  
    Created: 2024-02-20 14:30:00
    Status: Current
    ```
  </Step>
</Steps>

### Version Creation Reasons

Each memory version includes an `expiration_reason` field that explains why a new version was created:

<ResponseField name="expiration_reason" type="string">
  Indicates why this version was superseded by a new one.

  <Expandable title="Possible Values">
    **`updated`**\
    The memory was updated with new information that supersedes the old content. This is the most common reason - used when user preferences change, facts are corrected, or information is refined.

    <Example>
      * "User prefers tea" -> "User prefers coffee now"
      * "User lives in New York" -> "User moved to San Francisco"
    </Example>

    **`merged`**\
    Multiple related memories were combined into a single, more comprehensive memory during a merge conflict resolution or deduplication process.

    <Example>
      * "User likes Italian food" + "User enjoys pasta dishes" -> "User enjoys Italian cuisine, especially pasta"
    </Example>

    **`invalidated`**\
    The memory was determined to be incorrect, outdated, or no longer relevant based on new information.

    <Example>
      * "User is planning a trip to Japan" (invalidated after trip completed)
      * "User is interested in buying a car" (invalidated after purchase)
    </Example>

    **`conflict_resolved`**\
    A new version was created as the result of resolving a merge conflict, where multiple contradictory pieces of information were reconciled.

    **`system_correction`**\
    The memory was automatically corrected by the system due to detected errors or inconsistencies in the extraction process.
  </Expandable>
</ResponseField>

### Accessing Version History

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from recallrai import RecallrAI

    client = RecallrAI(api_key="rai_yourapikey", project_id="your-project-id")
    user = client.get_user("user123")

    # Retrieve memories with full version history
    memories = user.list_memories(
        include_previous_versions=True,
        limit=20
    )

    for memory in memories.items:
        print(f"Current Memory: {memory.content}")
        print(f"Version {memory.version_number} of {memory.total_versions}")
        
        # Access version history
        if memory.previous_versions:
            print("\nVersion History:")
            for version in memory.previous_versions:
                print(f"  Version {version.version_number}:")
                print(f"    Content: {version.content}")
                print(f"    Created: {version.created_at}")
                print(f"    Expired: {version.expired_at}")
                print(f"    Reason: {version.expiration_reason}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { RecallrAI } from "recallrai";

    const client = new RecallrAI({
    	apiKey: "rai_yourapikey",
    	projectId: "your-project-id",
    });

    const user = await client.getUser("user123");

    // Retrieve memories with full version history
    const memories = await user.listMemories({
    	includePreviousVersions: true,
    	limit: 20,
    });

    for (const memory of memories.items) {
    	console.log(`Current Memory: ${memory.content}`);
    	console.log(`Version ${memory.versionNumber} of ${memory.totalVersions}`);

    	// Access version history
    	if (memory.previousVersions) {
    		console.log("\nVersion History:");
    		for (const version of memory.previousVersions) {
    			console.log(`  Version ${version.versionNumber}:`);
    			console.log(`    Content: ${version.content}`);
    			console.log(`    Created: ${version.createdAt}`);
    			console.log(`    Expired: ${version.expiredAt}`);
    			console.log(`    Reason: ${version.expirationReason}`);
    		}
    	}
    }
    ```
  </Tab>
</Tabs>

<Info>
  Version history is included by default when listing memories. Set `include_previous_versions=False` (Python) or `includePreviousVersions: false` (Node.js) to retrieve only current versions for improved performance.
</Info>

### Benefits of Versioning

<CardGroup cols={2}>
  <Card title="Audit Trail" icon="clock-rotate-left">
    Track how user information changes over time with complete history and reasons for each change.
  </Card>

  <Card title="Conflict Resolution" icon="code-merge">
    Understand the context of merge conflicts by reviewing what information existed before the contradiction emerged.
  </Card>

  <Card title="Rollback Capability" icon="rotate-left">
    Access previous versions if new information turns out to be incorrect or if you need to analyze past states.
  </Card>

  <Card title="Debugging" icon="bug">
    Investigate issues in memory extraction by examining the full evolution of a memory and why versions changed.
  </Card>
</CardGroup>

<Warning>
  Memory versions are immutable once created. While you can see the full history, individual versions cannot be modified or deleted - only new versions can be created.
</Warning>