memories-lite

Lightweight memory layer for AI agents — LLM-based extraction, vector embeddings for retrieval, per-user isolation.

Quick Start

import { MemoriesLite } from 'memories-lite';

const memory = new MemoriesLite({
  llm: { provider: 'openai', config: { apiKey: 'KEY', model: 'gpt-5-mini' } },
  embedder: { provider: 'openai', config: { apiKey: 'KEY', model: 'text-embedding-3-small', dimension: 768 } },
  vectorStore: { provider: 'lite', config: { dimension: 768, rootPath: './data' } }
});

const userId = 'user-123';

// Capture a discussion → {title, summary}
await memory.capture(messages, userId, { metadata: { type: 'discussion' } });

// Capture or merge preferences into an existing memory (auto-load by ID)
await memory.captureOrUpdate(messages, userId, {
  existingMemoryId: 'abc-123',          // loads content + title from store
  metadata: { type: 'discussion', applyMode: 'MEM_ALWAYS' }
});

// Retrieve by semantic search
const results = await memory.retrieve('réponses courtes', userId, { filters: { type: 'discussion' } });

// CRUD
await memory.update(memoryId, 'New content', userId, { title: 'New title' });
await memory.delete(memoryId, userId);
const all = await memory.getAll(userId, { type: 'discussion' });

Architecture

Instruction mémorisable

Une instruction mémorisable est une règle de comportement durable liée à l'utilisateur courant, indiquant comment l'assistant doit se comporter au-delà du cas en cours.

Exemples :

• L'utilisateur souhaite qu'à l'avenir tu le tutoies et que tu répondes toujours en français.
• L'utilisateur utilise Windows 11 avec PowerShell (pas Linux).

Ce qui n'est pas mémorisable : actions ponctuelles ("envoie un email"), données métier, questions procédurales.

Two Capture Flows

Flow 1: capture() — Discussion → New Memory
─────────────────────────────────────────────
User clicks "Memorize" on a discussion
  └─> capture(messages, userId, { capturePrompt?, metadata })
        └─> LLM → { title, summary }
        └─> createMemory(summary, embed(title))

Flow 2: captureOrUpdate() — Discussion → Create or Merge
──────────────────────────────────────────────────────────
Agent tool or explicit user action
  └─> captureOrUpdate(messages, userId, {
        existingMemoryId?,    // if provided → auto-load + UPDATE (merge)
        metadata
      })
        ├─ if existingMemoryId:
        │    └─> get(existingMemoryId) → { memory, title }
        │    └─> buildCapturePrompt(memory) → merge prompt
        │    └─> LLM → complete merged set
        │    └─> updateMemory() (preserves title + ID)
        └─ else:
             └─> buildCapturePrompt() → capture prompt
             └─> LLM → { title, summary }
             └─> createMemory()

existingMemoryId est prioritaire : le contenu et le titre sont toujours chargés depuis le store.

Memory Apply Modes

| Mode | Injection | Use case | |------|-----------|----------| | MEM_ALWAYS | Automatic, every request | User preferences, permanent instructions | | MEM_SMART | Semantic search match | Discussion syntheses, knowledge patterns | | MEM_MANUAL | Explicit via rules[] | Session-specific rules |

Context Injection Flow

Memories are injected into the agent's system prompt via enrichSystemWithMemory():

enrichSystemWithMemory()
  ├─> getAll(userId, {type: 'discussion'})
  ├─> filter MEM_ALWAYS → globalInstructionsStr
  ├─> filter rules[]    → sessionInstructionsStr
  └─> renderContextInjection(profile, global, session, history)

Produces:
  <instructions>
  GLOBAL:
  L'utilisateur préfère les réponses courtes et structurées.
  L'utilisateur utilise Windows 11 et souhaite des exemples en PowerShell.
  </instructions>

Merge Rules (captureOrUpdate)

When merging new instructions with existing preferences:

| Case | Existing | New discussion | Result | |------|----------|---------------|--------| | Duplicate | "préfère le français" | "parle-moi en français" | Keep existing | | Refinement | "réponses courtes" | "courtes sauf pour les rapports" | Replace with refined | | Contradiction | "tutoiement" | "vouvoie-moi" | Replace with new | | New | (nothing) | "j'utilise macOS" | Add with date |

The LLM returns the complete merged set (not a diff). The title is preserved from the existing memory.

Memory Content Format

3rd person descriptive, grouped by date:

**2025-12-15**
L'utilisateur préfère les réponses courtes et structurées pour les résultats mfiles.
L'utilisateur souhaite que les formats "en gras" soient supprimés lors de la rédaction d'emails.
**2025-11-01**
L'utilisateur utilise Windows 11 et souhaite des exemples en shell.

API

capture(messages, userId, config)

Captures a discussion and generates a new memory with {title, summary}.

captureOrUpdate(messages, userId, config)

Captures and creates a new memory, or merges into an existing one if existingMemoryId is provided. The existing memory is auto-loaded from the store (content + title preserved).

retrieve(query, userId, config)

Semantic search. Returns only MEM_SMART memories.

getAll(userId, config)

List all memories (all apply modes).

get(memoryId, userId)

Get a single memory by ID.

update(memoryId, data, userId, metadata?)

Update memory content directly (no LLM).

delete(memoryId, userId)

Delete a memory.

Prompts

Built-in prompts (customizable via capturePrompt):

• DEFAULT_DISCUSSION_PROMPT — Synthesis of a discussion into title + summary
• DEFAULT_CAPTURE_PROMPT — Extraction of memorizable user instructions (3rd person format)
• DEFAULT_MERGE_RULES — Merge extension with <existing-preferences> injection

Utilities:

• buildCapturePrompt(existingContent?) — Assembles capture or merge prompt
• formatExistingPreferences(memories) — Formats memories as date-grouped bullet points

Acknowledgements

Forked from Mem0.

Inspired by: A-MEM, MemoryLLM, Reflexion.