local-llm-memory

Local-first chat memory with vector search for LLM applications

Store, search, and retrieve chat messages locally using semantic search. No cloud. No API keys. Your data stays on your device.

✨ Features

| Feature | Description | |---------|-------------| | 🔒 100% Local | All data stored on your device using LanceDB | | 🔍 Semantic Search | Find messages by meaning, not just keywords | | ⚡ Fast | Vector embeddings powered by transformers.js | | 📦 Zero Config | Works out of the box, no external services | | 🪶 Lightweight | ~80MB model, cached after first download | | 🔌 Framework Agnostic | Works with Electron, Node.js, React Native |

📦 Installation

npm install local-llm-memory

yarn add local-llm-memory

pnpm add local-llm-memory

🚀 Quick Start

import { ChatMemory } from 'local-llm-memory';

// Initialize the memory store
const memory = new ChatMemory({
  dataPath: './my-chat-data',  // Where to store data (default: ./chat-memory)
  maxMessages: 10000          // Max messages to keep (default: 10000)
});

// Initialize (downloads model on first run)
await memory.initialize();

// Add a message
await memory.addMessage(
  'The user prefers dark mode in all applications',
  { category: 'preference', userId: 'user-123' }
);

// Search semantically
const results = await memory.search('what are the user preferences?', {
  limit: 5,
  threshold: 0.7
});

console.log(results);
// [
//   {
//     text: 'The user prefers dark mode in all applications',
//     score: 0.89,
//     metadata: { category: 'preference', userId: 'user-123' },
//     timestamp: 1712345678000
//   }
// ]

📖 Usage Examples

Basic Chat Memory

import { ChatMemory } from 'local-llm-memory';

const memory = new ChatMemory();
await memory.initialize();

// Store conversation turns
await memory.addMessage('User asked about pricing', { role: 'user', topic: 'sales' });
await memory.addMessage('Explained the tiered pricing model', { role: 'assistant' });

// Find related context before responding
const context = await memory.search('pricing questions');

Electron App Integration

// main.js (Electron main process)
const { ChatMemory } = require('local-llm-memory');
const { app } = require('electron');

let memory;

app.whenReady().then(async () => {
  memory = new ChatMemory({
    dataPath: app.getPath('userData') + '/chat-memory'
  });
  
  await memory.initialize();
  console.log('Chat memory ready!');
});

// IPC handler for renderer
ipcMain.handle('chat:search', async (event, query) => {
  return await memory.search(query);
});

Custom Embedding Model

import { ChatMemory } from 'local-llm-memory';

const memory = new ChatMemory({
  embeddingModel: 'Xenova/all-MiniLM-L6-v2',  // Default model
  vectorSize: 384                            // Default dimensions
});

Memory Statistics

const stats = await memory.getStats();
console.log(stats);
// {
//   totalMessages: 1234,
//   dataSize: '12.5 MB',
//   oldestMessage: '2024-01-15T10:30:00.000Z',
//   newestMessage: '2024-04-14T15:45:00.000Z'
// }

Clear Memory

await memory.clear();
console.log('All chat memory cleared');

🔧 API Reference

new ChatMemory(options?)

Create a new chat memory instance.

| Option | Type | Default | Description | |--------|------|---------|-------------| | dataPath | string | ./chat-memory | Directory to store data | | maxMessages | number | 10000 | Maximum messages before FIFO deletion | | embeddingModel | string | Xenova/all-MiniLM-L6-v2 | HuggingFace model ID | | vectorSize | number | 384 | Embedding vector dimensions |

async initialize(progressCallback?)

Initialize the database and download embedding model if needed.

await memory.initialize((progress) => {
  console.log(`${progress.status}: ${progress.progress}%`);
});

async addMessage(text, metadata?)

Add a message to memory. Returns the message ID.

const id = await memory.addMessage('Important message', {
  source: 'user-input',
  priority: 'high'
});

async search(query, options?)

Semantic search across all messages.

| Option | Type | Default | Description | |--------|------|---------|-------------| | limit | number | 10 | Max results to return | | threshold | number | 0.5 | Minimum similarity score (0-1) |

const results = await memory.search('find important messages', {
  limit: 5,
  threshold: 0.7
});

async getStats()

Get memory statistics.

async clear()

Delete all messages.

🏗️ Architecture

┌───────────────────────────────────────────────────────────────┐
│                    LOCAL-LLM-MEMORY                           │
├───────────────────────────────────────────────────────────────┤
│                                                               │
│   Your Application                                            │
│       ↓                                                       │
│   ┌─────────────────────────────────────────────────────────┐│
│   │                 ChatMemory (API)                         ││
│   └─────────────────────────────────────────────────────────┘│
│       ↓                           ↓                          │
│   ┌─────────────────┐     ┌────────────────────┐             │
│   │ EmbeddingService │     │    LanceDB         │             │
│   │ (transformers.js)│     │ (Vector Database)  │             │
│   └─────────────────┘     └────────────────────┘             │
│       ↓                           ↓                          │
│   ┌─────────────────────────────────────────────────────────┐│
│   │              Local File System                          ││
│   │              ./chat-memory/                             ││
│   └─────────────────────────────────────────────────────────┘│
│                                                               │
│   NO CLOUD. NO API KEYS. NO EXTERNAL SERVICES.              │
│                                                               │
└───────────────────────────────────────────────────────────────┘

💡 Use Cases

| Use Case | Description | |----------|-------------| | AI Chatbots | Remember conversation context across sessions | | Personal Assistants | Store and retrieve user preferences | | Customer Support | Find similar past questions and answers | | Research Tools | Build searchable knowledge base from notes | | Note-Taking Apps | Semantic search over personal notes |

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📝 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• LanceDB - Serverless vector database
• Transformers.js - Local ML models
• Xenova/all-MiniLM-L6-v2 - Embedding model

📊 Comparison

| Feature | local-llm-memory | Pinecone | Chroma | Weaviate | |---------|------------------|----------|--------|----------| | Self-Hosted | ✅ | ❌ | ✅ | ✅ | | Zero Config | ✅ | ❌ | ⚠️ | ❌ | | No API Keys | ✅ | ❌ | ✅ | ✅ | | Browser Support | ⚠️ | ❌ | ❌ | ❌ | | Node.js Support | ✅ | ✅ | ✅ | ✅ | | Embedding Included | ✅ | ⚠️ | ⚠️ | ⚠️ | | Cost | Free | $$$ | Free | Free |