@aksolab/recall

A memory management for AI applications using that provides persistent core memory, chat history management, and RAG (Retrieval-Augmented Generation) capabilities.

Features

• 🧠 Core Memory: Persistent memory that stays in system messages
• 💬 Chat History: Manage conversation history across multiple threads
• 📚 Archive Memory: RAG (Retrieval-Augmented Generation) support for long-term memory
• 🔄 Multiple Storage Providers: Support for in-memory and Redis storage also add your own

Installation

npm install @aksolab/recall
# or
yarn add @aksolab/recall
# or
pnpm add @aksolab/recall

Quick Start

import { Recall } from '@aksolab/recall';
import { RedisProvider } from '@aksolab/recall-redis-storage-adapter';
import { RedisArchiveProvider } from '@aksolab/recall-redis-search-adapter';
import { createClient } from 'redis';

// Initialize Redis client
const redisClient = createClient({ url: process.env.REDIS_URL });
await redisClient.connect();

// Initialize storage provider
const storage = new RedisProvider({
  client: redisClient,
  prefix: 'user_123'  // Optional: prefix for Redis keys
});

// Initialize archive provider for RAG capabilities
const archive = new RedisArchiveProvider({
  client: redisClient,
  indexName: 'idx:user_memory',  // Optional: defaults to 'idx:archive'
  collectionName: 'user_123:archive:',  // Optional: defaults to 'recall:memory:archive:'
  dimensions: 1536  // Optional: for text-embedding-3-small
});

// Initialize Recall with configured providers
const memory = new Recall({
  storageProvider: storage,
  archiveProvider: archive,
  openaiApiKey: process.env.OPENAI_API_KEY,
  memoryKey: 'user_123',
  threadId: 'main',
  memoryOptions: { // optional
    maxContextSize: 25000,     // Custom max context size
    coreBlockTokenLimit: 3000, // Custom core block token limit
    chatTokenLimit: 15000,     // Custom chat token limit
  },
  coreBlocks: [
    {
      key: 'user_context',
      description: 'Essential information about the user',
      defaultContent: 'User name is Alice. She prefers quick, concise responses.',
      readOnly: false
    },
    {
      key: 'assistant_persona',
      description: 'Assistant personality and behavior settings',
      defaultContent: 'I am Nova, a helpful AI assistant focused on clear communication.',
      readOnly: true
    }
  ]
});

// Add messages directly to the memory instance
await memory.addMessages({ content: 'Hello!', role: 'user' });

// Add multiple messages at once
await memory.addMessages([
  { content: 'Hi there!', role: 'assistant' },
  { content: 'How can I help?', role: 'assistant' }
]);

Memory Limits Configuration

Recall provides configurable memory limits to help manage token usage and context size:

• chatTokenLimit: Maximum number of tokens in chat history (default: 10000)
• maxContextSize: Maximum total context size in tokens (default: 20000)
• coreBlockTokenLimit: Maximum tokens per core memory block (default: 2000)

You can set these limits during initialization:

const memory = new Recall({
  storageProvider: storage,
  archiveProvider: archive,
  openaiApiKey: process.env.OPENAI_API_KEY,
  memoryKey: 'user_123',
  threadId: 'main',
  maxContextSize: 25000,     // Custom max context size
  coreBlockTokenLimit: 3000, // Custom core block token limit
  chatTokenLimit: 15000,     // Custom chat token limit
  coreBlocks: [
    // ... core blocks configuration ...
  ]
});

These limits help manage memory and token usage:

• chatTokenLimit: When exceeded, older messages are automatically summarized
• maxContextSize: Ensures total context stays within model limits
• coreBlockTokenLimit: Prevents individual core memory blocks from becoming too large

The limits can also be updated after initialization:

// Update limits as needed
memory.maxContextSize = 30000;
memory.chatTokenLimit = 20000;
memory.coreBlockTokenLimit = 4000;

Core Memory

Core Memory is a persistent memory system that's always present in the system prompt. It allows both users and AI agents to maintain and update important contextual information throughout conversations.

How Core Memory Works

• Core Memory is included in every system prompt
• Can be organized into blocks with different purposes
• Each block can be marked as read-only or updatable
• AI agents can update their own memory during conversations
• Persists across multiple chat sessions
• Automatically initializes with default content

Example Usage

const memory = new Recall({
  // ... provider configuration ...
  coreBlocks: [
    {
      key: 'user_preferences',
      description: 'User preferences and settings',
      defaultContent: 'Language: English, Tone: Professional',
      readOnly: false
    },
    {
      key: 'agent_persona',
      description: 'AI personality settings',
      defaultContent: 'You are a helpful technical assistant',
      readOnly: true
    }
  ]
});

// Pass tools to AI Agent
import { generateText } from 'ai';

const result = await generateText({
  model: 'gpt-4',
  tools: memory.tools,  // Memory tools are automatically available to the AI
  messages: [
    {
      role: 'system',
      content: 'You are a helpful assistant that remembers user preferences.'
    },
    {
      role: 'user',
      content: 'Remember that I prefer technical explanations and my name is Alex.'
    }
  ],
});

The AI agent will have access to these memory management tools:

• coreMemoryReplace: Update entire memory blocks
• coreMemoryAppend: Add information to existing blocks
• archivalMemorySearch: Search through archived information
• archivalMemoryInsert: Add new information to archive

Chat History

Chat History maintains the ongoing conversation between users and AI Agents, including message history, tool calls, and automatic conversation summarization.

Features

• Automatic token limit management
• Smart conversation summarization
• Multiple conversation threads
• Tool call history preservation
• Context-aware message handling

Example Usage

// Create a memory instance with different thread IDs
const memory = new Recall({
  storageProvider,
  archiveProvider,
  openaiApiKey: process.env.OPENAI_API_KEY,
  memoryKey: 'user_123',
  threadId: 'main'  // Main conversation thread
});

const analyticsMemory = new Recall({
  storageProvider,
  archiveProvider,
  openaiApiKey: process.env.OPENAI_API_KEY,
  memoryKey: 'user_123',
  threadId: 'analytics'  // Analytics-specific thread
});

// Add messages
await memory.addMessages({
  content: 'Analyze this dataset',
  role: 'user'
});

await memory.addMessages({
  content: 'I\'ll analyze the data',
  role: 'assistant',
  tool_calls: [{
    type: 'function',
    function: {
      name: 'analyzeData',
      arguments: { dataset: 'sales_2024.csv' }
    }
  }]
});

// Add multiple messages at once
await memory.addMessages([
  { content: 'Here are the results', role: 'assistant' },
  { content: 'Thanks!', role: 'user' }
]);

// Get history
const history = await memory.chatHistory();

Archive Memory (RAG)

Archive Memory provides RAG capabilities for long-term information storage and retrieval. It supports multiple search methods:

• Text-based search with fuzzy matching
• Semantic search using embeddings
• Hybrid search combining both approaches

Example Usage

// Store information using tools
await memory.tools.archivalMemoryInsert({
  content: 'User prefers vegetarian food',
  name: 'Dietary Preferences',  // Optional: name for the entry
  metadata: { category: 'preferences' }  // Optional: additional metadata
});

// Text-based search
const textResults = await memory.tools.archivalMemorySearch({
  query: 'food preferences',
  type: 'text'
});

// Semantic search
const semanticResults = await memory.tools.archivalMemorySearch({
  query: 'dietary restrictions',
  type: 'similarity'
});

// Hybrid search (combines text and semantic search)
const hybridResults = await memory.tools.archivalMemorySearch({
  query: 'food allergies',
  type: 'hybrid',
  vectorWeight: 0.7,  // Optional: weight for semantic search (default: 0.7)
  textWeight: 0.3    // Optional: weight for text search (default: 0.3)
});

// Get chat history
const history = await memory.chatHistory();

Each search result includes:

• The matched entry with its content and metadata
• A relevance score (0-100)
• Match details for text searches (exact phrases and matched terms)

Storage Providers

Recall supports multiple storage providers for different use cases.

Built-in Providers

• InMemoryProvider: Great for testing and development
• RedisProvider: Production-ready persistent storage

Redis Requirements

To use Redis providers, you need:

• Redis Stack with RediSearch module installed
• Redis version 6.0 or higher
• Node Redis client v4.7.0 or higher

For development:

docker run -d --name redis-stack -p 6379:6379 redis/redis-stack:latest

For production, ensure your Redis instance has the RediSearch module installed. Then initialize the providers:

import { Recall } from '@aksolab/recall';
import { RedisProvider, setupRedisSchema } from '@aksolab/recall-redis-storage-adapter';
import { RedisArchiveProvider } from '@aksolab/recall-redis-search-adapter';
import { createClient } from 'redis';

// Initialize Redis client
const client = createClient({
  url: process.env.REDIS_URL,
  // Add any additional configuration options
});
await client.connect();

// Optional but recommended: Set up Redis schema once during app initialization
// This creates necessary indexes for vector search and validates existing schema
await setupRedisSchema(
  client,
  'idx:archive',      // Optional: index name
  'user:archive:',    // Optional: collection prefix
  1536,              // Optional: vector dimensions
  false              // Optional: force schema recreation
);

// Initialize storage provider for chat history and core memory
const storage = new RedisProvider({
  client,
  prefix: 'user:memory:'  // Optional: prefix for Redis keys
});

// Initialize archive provider for RAG capabilities
const archive = new RedisArchiveProvider({
  client,
  indexName: 'idx:archive',      // Optional: defaults to 'idx:archive'
  collectionName: 'user:archive:', // Optional: defaults to 'recall:memory:archive:'
  dimensions: 1536,              // Optional: for text-embedding-3-small
  embeddingModel: 'text-embedding-3-small'  // Optional: defaults to text-embedding-3-small
});

// Initialize Recall with configured providers
const recall = new Recall({
  storageProvider: storage,
  archiveProvider: archive,
  openaiApiKey: process.env.OPENAI_API_KEY,
  memoryKey: 'user_123',
  threadId: 'main'
});

The Redis schema setup:

• Is optional but recommended for production use
• Should be done once during application initialization
• Creates necessary indexes for vector search
• Validates existing schema if already present
• Can be forced to recreate with the force parameter
• Is safe to run multiple times (won't recreate if valid)
• Will log a warning if missing when using the archive provider

The providers will automatically:

• Handle vector embeddings for semantic search
• Manage JSON storage and retrieval
• Provide text, semantic, and hybrid search capabilities

Custom Providers

You can implement custom providers by extending the base interfaces:

import { StorageProvider } from '@aksolab/recall-storage-provider';
import { ArchiveProvider } from '@aksolab/recall-archive-provider';
import { Recall } from '@aksolab/recall';

class CustomStorageProvider implements StorageProvider {
  // Implement storage methods
}

class CustomArchiveProvider implements ArchiveProvider {
  // Implement archive methods
}

// Use custom providers with Recall
const memory = new Recall({
  storageProvider: new CustomStorageProvider(),
  archiveProvider: new CustomArchiveProvider(),
  // ... other configuration
});

Using with AI Agents

Memory tools can be passed directly to AI agents for autonomous memory management:

import { generateText } from 'ai';

// Initialize memory and create session as shown in Quick Start
const session = await memory.createChatSession('user_123', 'main');
const { tools } = session;

const result = await generateText({
  model: 'gpt-4',
  tools,  // Pass the memory tools to the AI
  messages: [
    {
      role: 'system',
      content: 'You are a helpful assistant that remembers user preferences.'
    },
    {
      role: 'user',
      content: 'I prefer to be called Alex and like technical, detailed explanations.'
    }
  ],
});

// The AI can now use tools to manage memory
// For example, it might call:
// tools.coreMemoryReplace({
//   block: 'user_preferences',
//   content: 'Name: Alex, Preference: Technical and detailed explanations'
// })

// Later in the conversation, AI can retrieve preferences
const result2 = await generateText({
  model: 'gpt-4',
  tools,
  messages: [
    {
      role: 'user',
      content: 'Can you explain how databases work?'
    }
  ],
});

// AI can search archive memory for relevant information
// tools.archivalMemorySearch({
//   query: 'user Alex technical preferences'
// })

The available tools include:

• coreMemoryReplace: Update entire memory blocks
• coreMemoryAppend: Add information to existing blocks
• archivalMemorySearch: Search through archived information
• archivalMemoryInsert: Add new information to archive

Contributing

Commit Messages

This project uses semantic versioning based on commit message prefixes. Your commit message should be structured as follows:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types that trigger version updates:

• feat: New feature (minor version bump)
• fix: Bug fix (patch version bump)
• perf: Performance improvement (patch version bump)
• BREAKING CHANGE: Breaking API change (major version bump)

Examples:

# Patch release (0.0.x)
git commit -m "fix: correct memory leak in chat history"
git commit -m "perf: improve archive search performance"

# Minor release (0.x.0)
git commit -m "feat: add new core memory block type"

# Major release (x.0.0)
git commit -m "feat!: redesign storage provider API
BREAKING CHANGE: storage provider interface has changed"

The version number will be automatically updated when merging to main branch.

License

MIT