Memories - RecallrAI Documentation

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 for each project. You can create custom categories that match your application’s needs.

Access the Dashboard

Navigate to your project settings in the Recallr Dashboard.

Create a Category

Add a new category with a descriptive name and optional description.

name

string

required

Use descriptive, lowercase names with underscores (e.g., food_preferences, medical_history).

description

string

Optional description explaining what this category contains.

Use Categories

Once created, Recallr will automatically assign memories to appropriate categories during extraction, and you can filter memories by category when retrieving them.

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.

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

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

Inclusion Instructions

Custom instructions to guide what aspects should be included in generated memories.

inclusion_instructions

array of strings

List of specific instructions to emphasize certain aspects during memory extraction.

Show Example

[
  "Always capture specific product names and brands mentioned",
  "Include temporal context for events (when something happened)",
  "Extract numerical measurements and quantities precisely"
]

Positive Examples

Examples of well-formatted, high-quality memories to guide the extraction model.

positive_examples

array of strings

Short examples demonstrating the desired memory format and content.

Show Example

[
  "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"
]

Provide 3-5 positive examples that represent the ideal structure and detail level for your use case.

Exclusion Instructions

Instructions to prevent certain types of information from being stored as memories.

exclusion_instructions

array of strings

Specific guidelines for what to avoid capturing as memories.

Show Example

[
  "Do not store temporary session-specific information",
  "Exclude casual greetings and pleasantries",
  "Ignore hypothetical scenarios or 'what-if' discussions"
]

Use exclusion instructions to avoid storing sensitive information, temporary data, or noise that doesn’t provide long-term value.

Negative Examples

Examples of poor-quality memories that should be avoided.

negative_examples

array of strings

Short examples showing what NOT to extract as memories.

Show Example

[
  "User said hello",
  "The weather was discussed",
  "User asked a question"
]

False Positive Examples

Memories that were incorrectly extracted when they shouldn’t have been (actual negative, predicted positive).

false_positive_examples

array of strings

Examples where the system incorrectly created a memory. Use these to fine-tune extraction precision.

Show Use Case

Help the model learn from past mistakes by showing examples of information that was extracted but shouldn’t have been.

False Negative Examples

Important information that was missed during extraction (actual positive, predicted negative).

false_negative_examples

array of strings

Examples where the system failed to create a memory that should have been created. Use these to improve extraction recall.

Show Use Case

Teach the model to catch important information it previously missed.

Similarity Check Configuration

Control how Recallr checks for redundant memories during generation.

top_k_symantic_similarity_check

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.

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.

Merge Conflict Handling

Configure whether the system should raise merge conflicts for ambiguous situations.

raise_merge_conflict

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.

Enable merge conflicts for critical applications where you need human review of ambiguous updates. Disable for faster processing when automated resolution is acceptable.

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:

Low Latency

Fastest retrieval with basic semantic search. Best for real-time applications where speed is critical.

Balanced

Combines multiple retrieval techniques for better accuracy with reasonable performance. Recommended for most use cases.

Agentic

Most comprehensive search using subqueries, keywords, and semantic similarity. Best when accuracy is paramount.

Recall Preferences

Configure these settings for Balanced and Agentic recall strategies:

Custom Instructions

Guide the subquery and keyword generation process with specific instructions.

custom_instructions

array of strings

Instructions to help generate better search queries and keywords from user messages.

Show Example

[
  "Focus on extracting the user's intent and goal",
  "Include domain-specific terminology in keywords",
  "Consider temporal context when generating subqueries"
]

Subquery Configuration

Control how subquery-based recall contributes to memory retrieval.

subqueries_candidate_memories_weight

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.

example_subqueries

array of strings

Example subqueries to guide the generation process.

Show Example

[
  "What are the user's dietary restrictions?",
  "Has the user mentioned any health conditions?",
  "What products has the user purchased before?"
]

Keyword Configuration

Control how keyword-based recall contributes to memory retrieval.

keywords_candidate_memories_weight

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.

example_keywords

array of strings

Example keywords to guide the extraction process.

Show Example

[
  "allergy, peanuts, shellfish",
  "preference, vegetarian, organic",
  "medical, diabetes, medication"
]

Summary Search Examples

Guide how the system generates questions for searching session summaries.

example_summary_search_questions

array of strings

Example questions that help retrieve relevant session summaries.

Show Example

[
  "What did the user say about their preferences?",
  "What problems or issues has the user mentioned?",
  "What are the user's goals and objectives?"
]

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.

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.

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

New Information Emerges

During a later session, contradictory or updated information appears.

User: "Actually, I prefer text messages now instead of email"

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

Version Creation Reasons

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

expiration_reason

string

Indicates why this version was superseded by a new one.

Show 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.merged
Multiple related memories were combined into a single, more comprehensive memory during a merge conflict resolution or deduplication process.invalidated
The memory was determined to be incorrect, outdated, or no longer relevant based on new information.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.

Accessing Version History

Python
Node.js

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}")

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}`);
		}
	}
}

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.

Benefits of Versioning

Audit Trail

Track how user information changes over time with complete history and reasons for each change.

Conflict Resolution

Understand the context of merge conflicts by reviewing what information existed before the contradiction emerged.

Rollback Capability

Access previous versions if new information turns out to be incorrect or if you need to analyze past states.

Debugging

Investigate issues in memory extraction by examining the full evolution of a memory and why versions changed.

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.

​What are Memories?

​Memory Categories

​Managing Categories

​Customizing Memory Extraction

​Generation Preferences

​Customizing Memory Recall

​Recall Strategies

Low Latency

Balanced

Agentic

​Recall Preferences

​Memory Versioning

​How Versioning Works

​Version Creation Reasons

​Accessing Version History

​Benefits of Versioning

Audit Trail

Conflict Resolution

Rollback Capability

Debugging

What are Memories?

Memory Categories

Managing Categories

Customizing Memory Extraction

Generation Preferences

Customizing Memory Recall

Recall Strategies

Recall Preferences

Memory Versioning

How Versioning Works

Version Creation Reasons

Accessing Version History

Benefits of Versioning