memories-lite 0.99.5 → 0.99.9

package/README.md

@@ -1,196 +1,169 @@
-# 🧠 Memories-lite
+# memories-lite
 
-> **A lightweight memory layer for AI agents, leveraging LLMs for fact extraction and vector embeddings for retrieval.**
+> Lightweight memory layer for AI agents — LLM-based extraction, vector embeddings for retrieval, per-user isolation.
 
-## 📋 Table of Contents
-- [Quick Start](#-quick-start)
-- [Installation](#-installation)
-- [Basic Usage](#-basic-usage)
-- [Key Features](#-key-features)
-- [Memory Types](#-memory-types)
-- [Use Cases](#-use-cases) 
-- [Advanced Configuration](#-advanced-configuration)
-- [Documentation](#-documentation)
-- [Acknowledgements](#-acknowledgements)
+## Quick Start
 
-## 🚀 Quick Start
-
-```bash
-# Install the package
-npm install memories-lite
-
-# Basic usage
+```typescript
 import { MemoriesLite } from 'memories-lite';
 
 const memory = new MemoriesLite({
-  llm: {
-    provider: 'openai',
-    config: { apiKey: 'YOUR_API_KEY' }
-  },
-  embedder: {
-    provider: 'openai',
-    config: { apiKey: 'YOUR_API_KEY', model: 'text-embedding-3-small' }
-  }
+  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' } }
 });
 
-// Add a memory for a user
-await memory.capture("I prefer dark chocolate over milk chocolate", "user123");
+const userId = 'user-123';
+
+// Capture a discussion → {title, summary}
+await memory.capture(messages, userId, { metadata: { type: 'discussion' } });
 
-// Retrieve relevant memories
-const results = await memory.retrieve("What are my food preferences?", "user123");
+// 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' });
 ```
 
-## 🌟 Highlights
+## Architecture
 
-- **Higher Performance**: Optimized memory operations that run significantly faster than mem0
-- **Business-Centric Design**: Simplified API and workflows specifically tailored for business use cases
-- **Advanced Hybrid Scoring**: Improved relevance through a custom scoring algorithm that balances vector similarity, recency, and importance
-- **Enhanced Security**: One database per user architecture that provides stronger isolation and data protection
-- **Streamlined Implementation**: Focused on essential features with minimal dependencies
+### Instruction mémorisable
 
-## 📥 Installation
+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.
 
-```bash
-npm install memories-lite
-# or
-yarn add memories-lite
-```
+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).`
 
-## 🔍 Basic Usage
+Ce qui n'est **pas** mémorisable : actions ponctuelles ("envoie un email"), données métier, questions procédurales.
 
-```typescript
-import { MemoriesLite } from 'memories-lite';
+### Two Capture Flows
 
-// Basic configuration
-const memory = new MemoriesLite({
-  llm: {
-    provider: 'openai',
-    config: { apiKey: 'YOUR_OPENAI_API_KEY' }
-  },
-  embedder: {
-    provider: 'openai',
-    config: { apiKey: 'YOUR_OPENAI_API_KEY' }
-  }
-  // Vector store defaults to an in-memory store
-});
+```
+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()
+```
 
-// Unique ID for each user
-const userId = 'user-123';
+`existingMemoryId` est prioritaire : le contenu et le titre sont toujours chargés depuis le store.
 
-// Add memories
-await memory.capture('I love Italian food', userId);
+### Memory Apply Modes
 
-// Retrieve relevant memories
-const results = await memory.retrieve('What foods do I like?', userId);
-console.log('Relevant memories:', results.results.map(m => m.memory));
+| 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 |
 
-// Update a memory
-if (results.results.length > 0) {
-  await memory.update(results.results[0].id, 'I love Italian and French cuisine', userId);
-}
+### Context Injection Flow
 
-// Delete a memory
-if (results.results.length > 0) {
-  await memory.delete(results.results[0].id, userId);
-}
+Memories are injected into the agent's system prompt via `enrichSystemWithMemory()`:
 
-// Get all memories for a user
-const allMemories = await memory.getAll(userId, {});
+```
+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>
 ```
 
-## 🔑 Key Features
+### Merge Rules (captureOrUpdate)
 
-- **Memory Capture**: Extract and store relevant information from conversations
-- **Contextual Retrieval**: Find memories most relevant to the current query
-- **User Isolation**: Each user's memories are stored separately for privacy and security
-- **Memory Types**: Support for different types of memories (factual, episodic, etc.)
-- **Custom Scoring**: Hybrid scoring system balancing similarity, recency, and importance
+When merging new instructions with existing preferences:
 
-## 🧩 Memory Types
+| 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 |
 
-Memories-lite supports four main types of memory:
+The LLM returns the **complete merged set** (not a diff). The title is preserved from the existing memory.
 
-1. **Factual Memory** ✓
-   - User preferences, traits, and personal information
-   - Example: "User likes Italian cuisine"
+### Memory Content Format
 
-2. **Episodic Memory** ⏱️
-   - Time-based events and interactions
-   - Example: "User has a meeting tomorrow at 2pm"
+3rd person descriptive, grouped by date:
 
-3. **Semantic Memory** 🧠
-   - General knowledge and concepts
-   - Example: "Yoga is beneficial for mental health"
+```
+**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.
+```
 
-4. **Procedural Memory** 🔄
-   - Step-by-step processes and workflows
-   - Example: "Steps to configure the company VPN"
+## API
 
-## 💼 Use Cases
+### `capture(messages, userId, config)`
+Captures a discussion and generates a new memory with `{title, summary}`.
 
-- **Customer Support Bots**: Remember customer preferences and past interactions
-- **Personal Assistants**: Build context-aware AI assistants that learn about user preferences
-- **Business Applications**: Integrate with enterprise systems to maintain contextual awareness
-- **Educational Tools**: Create learning assistants that remember student progress
+### `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).
 
-## ⚙️ Advanced Configuration
+### `retrieve(query, userId, config)`
+Semantic search. Returns only `MEM_SMART` memories.
 
-```typescript
-// Custom scoring for different memory types
-const customMemory = new MemoriesLite({
-  llm: {
-    provider: 'openai',
-    config: { apiKey: 'YOUR_API_KEY' }
-  },
-  embedder: {
-    provider: 'openai', 
-    config: { apiKey: 'YOUR_API_KEY' }
-  },
-  vectorStore: {
-    provider: 'lite',
-    config: {
-      dimension: 1536,
-      scoring: {
-        // Prioritize factual memories with long retention
-        factual: { alpha: 0.7, beta: 0.2, gamma: 0.1, halfLifeDays: 365 },
-        // Make preferences permanently available
-        assistant_preference: { alpha: 0.6, beta: 0.0, gamma: 0.4, halfLifeDays: Infinity },
-      }
-    }
-  }
-});
-```
+### `getAll(userId, config)`
+List all memories (all apply modes).
 
-## 📚 Documentation
+### `get(memoryId, userId)`
+Get a single memory by ID.
 
-For detailed technical information and implementation details, see:
+### `update(memoryId, data, userId, metadata?)`
+Update memory content directly (no LLM).
 
-- [TECHNICAL.md](./TECHNICAL.md) - Technical implementation details
-- [MEMORIES.md](./MEMORIES.md) - Detailed memory models and concepts
+### `delete(memoryId, userId)`
+Delete a memory.
 
-## 🙏 Acknowledgements
+## Prompts
 
-Forked from the [Mem0](https://github.com/mem0ai/mem0) project ❤️.
+Built-in prompts (customizable via `capturePrompt`):
 
-Inspired by research concepts from:
-- **A-MEM**: Agentic Memory for LLM Agents
-- **MemoryLLM**: Self-Updatable Large Language Models
-- **Reflexion**: Language Agents with Verbal Reinforcement Learning
+- `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
 
-## 📝 Development Roadmap
+Utilities:
+- `buildCapturePrompt(existingContent?)` — Assembles capture or merge prompt
+- `formatExistingPreferences(memories)` — Formats memories as date-grouped bullet points
 
-- [x] **Semantic Memory Typing & Structuring**: Explicitly tagging and utilizing memory types (factual, episodic, semantic, procedural)
-- [x] **Implicit Memory Updates**: Auto-merging memories based on context without explicit ID references
-- [x] **Virtual Sessions/Context Grouping**: Group memories related to specific conversation contexts
-- [x] **User Isolation**: Separate storage per user for enhanced security and data privacy
-- [x] **Memory Type Detection**: LLM-based automatic classification of memory types
-- [x] **Core Memory Operations**: Basic CRUD operations with user-specific isolation
-- [x] **Memory Decay & Scoring**: Hybrid scoring with recency decay and importance weights
-- [ ] **Reflexion Pattern Integration**: Self-correction loops for memory refinement
-- [x] **Memory Recency**: Prioritizing memories based on importance and time decay
-- [x] **Edge Case Tests**: Complete unit tests for episodic and factual memory edge cases
-- [ ] **Middleware Support**: Hooks and middleware for custom processing pipelines
+## Acknowledgements
 
-## 📄 License
+Forked from [Mem0](https://github.com/mem0ai/mem0).
 
-MIT
+Inspired by: A-MEM, MemoryLLM, Reflexion.

package/ROADMAP.md

@@ -0,0 +1,75 @@
+# memories-lite — Roadmap
+
+## Completed
+
+- [x] Semantic Memory Typing & Structuring (factual, episodic, procedural)
+- [x] Implicit Memory Updates via LLM
+- [x] Virtual Sessions/Context Grouping
+- [x] User Isolation (per-user vector store)
+- [x] Memory Decay & Scoring (hybrid: cosine similarity + recency + importance)
+- [x] Memory Recency (half-life per type)
+- [x] Discussion Synthesis (`capture()` with title + summary)
+- [x] ApplyMode system (MEM_ALWAYS / MEM_SMART / MEM_MANUAL)
+- [x] `captureOrUpdate()` with merge support
+
+## In Progress
+
+- [ ] Tool `saveUserPreference` integration in agentic-server
+
+## Planned
+
+- [ ] Reflexion Pattern Integration — self-correction loops for memory refinement
+- [ ] Middleware Support — hooks for custom processing pipelines
+
+## Deprecated (v1 → v2 migration)
+
+### Automatic 4-type extraction (deprecated)
+
+The original system automatically classified memories into 4 types via LLM. This produced too many false positives in production. The v2 approach lets the user explicitly control what gets memorized.
+
+#### Memory Types (historical reference)
+
+1. **Factual Memory** — User preferences, traits, personal information
+   - Example: "Aime la cuisine italienne", "Parle couramment l'espagnol"
+
+2. **Episodic Memory** — Events associated with time/place
+   - Example: "A assisté à un concert à Paris en 2023"
+
+3. **Semantic Memory** — Concepts, relations, general knowledge
+   - Example: "Le yoga est bénéfique pour la santé mentale"
+
+4. **Procedural Memory** — Processes, action sequences
+   - Example: "Sait comment préparer un café latte"
+
+#### Why deprecated
+
+- Too many false positives in type classification
+- Automatic extraction stored irrelevant information
+- Update/merge was fragile (LLM deciding ADD/UPDATE/DELETE)
+- The v2 approach: user controls when to memorize, format is "L'utilisateur [verbe] [context]"
+
+### Scoring Coefficients (still active for compatibility)
+
+| Type | α (similarity) | β (recency) | γ (importance) |
+|------|---------------|-------------|----------------|
+| procedural | 0.30 | 0.40 | 0.05 |
+| episodic | 0.40 | 0.50 | 0.10 |
+| assistant_preference | 0.60 | 0.05 | 0.35 |
+| discussion | 1.00 | 0.00 | 0.00 |
+
+### Half-life per type
+
+| Type | HL (days) | λ |
+|------|-----------|---|
+| procedural | 1 | 0.693 |
+| episodic | 7 | 0.099 |
+| assistant_preference | ∞ | 0 |
+| discussion | ∞ | 0 |
+
+## Research References
+
+- [Zep: Temporal Knowledge Graph for Agent Memory](https://arxiv.org/abs/2501.13956)
+- [A-MEM: Agentic Memory for LLM Agents](https://arxiv.org/abs/2402.12110)
+- [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366)
+- [MemoryLLM: Self-Updatable Large Language Models](https://arxiv.org/abs/2402.04624)
+- [OpenAI Context Engineering for Personalization](https://cookbook.openai.com/examples/agents_sdk/context_personalization)

package/dist/memory/index.d.ts

@@ -31,6 +31,20 @@ export declare class MemoriesLite {
      * @param config - Options incluant capturePrompt pour personnaliser la synthèse
      */
     capture(messages: string | Message[], userId: string, config: AddMemoryOptions): Promise<SearchResult>;
+    /**
+     * Capture une discussion et crée ou met à jour une mémoire existante (merge)
+     *
+     * - Sans existingMemoryId → CREATE : extraction d'instructions + nouvelle mémoire
+     * - Avec existingMemoryId → UPDATE : charge la mémoire depuis le store, merge les
+     *   nouvelles instructions avec les existantes, met à jour en conservant le titre
+     *
+     * existingMemoryId est prioritaire sur existingContent (toujours chargé depuis le store).
+     *
+     * @param messages - Messages de la discussion ou texte brut
+     * @param userId - ID utilisateur
+     * @param config - Options (existingMemoryId pour le merge, metadata, capturePrompt override)
+     */
+    captureOrUpdate(messages: string | Message[], userId: string, config: AddMemoryOptions): Promise<SearchResult>;
     get(memoryId: string, userId: string): Promise<MemoryItem | null>;
     retrieve(query: string, userId: string, config: SearchMemoryOptions): Promise<SearchResult>;
     /**

package/dist/memory/index.js

@@ -193,6 +193,133 @@ class MemoriesLite {
             results: vectorStoreResult,
         };
     }
+    /**
+     * Capture une discussion et crée ou met à jour une mémoire existante (merge)
+     *
+     * - Sans existingMemoryId → CREATE : extraction d'instructions + nouvelle mémoire
+     * - Avec existingMemoryId → UPDATE : charge la mémoire depuis le store, merge les
+     *   nouvelles instructions avec les existantes, met à jour en conservant le titre
+     *
+     * existingMemoryId est prioritaire sur existingContent (toujours chargé depuis le store).
+     *
+     * @param messages - Messages de la discussion ou texte brut
+     * @param userId - ID utilisateur
+     * @param config - Options (existingMemoryId pour le merge, metadata, capturePrompt override)
+     */
+    async captureOrUpdate(messages, userId, config) {
+        const { agentId, runId, metadata = {}, filters = {}, capturePrompt, existingMemoryId, existingContent, } = config;
+        if (agentId)
+            filters.agentId = metadata.agentId = agentId;
+        if (runId)
+            filters.runId = metadata.runId = runId;
+        if (!userId && !filters.agentId && !filters.runId) {
+            throw new Error("One of the filters: userId, agentId or runId is required!");
+        }
+        const parsedMessages = Array.isArray(messages)
+            ? messages
+            : [{ role: "user", content: messages }];
+        const final_parsedMessages = await (0, memory_1.parse_vision_messages)(parsedMessages);
+        //
+        // existingMemoryId est prioritaire : toujours charger depuis le store pour le contenu et le titre
+        let resolvedContent = existingContent;
+        let existingTitle;
+        if (existingMemoryId) {
+            const existing = await this.get(existingMemoryId, userId);
+            if (existing) {
+                resolvedContent = existing.memory;
+                existingTitle = existing.metadata?.title;
+            }
+        }
+        //
+        // Construire le prompt : merge si resolvedContent disponible, sinon capture simple
+        const effectivePrompt = capturePrompt || (0, prompts_1.buildCapturePrompt)(resolvedContent);
+        const $t = this.$t;
+        const vectorStore = await this.getVectorStore(userId);
+        //
+        // Formater les messages pour la synthèse
+        const formattedMessages = final_parsedMessages
+            .filter((m) => typeof m.content === 'string')
+            .map((m) => `**${m.role.toUpperCase()}**: ${$t(m.content)}`)
+            .join("\n\n");
+        //
+        // Générer la synthèse via LLM
+        const [systemPrompt, userPrompt] = (0, prompts_1.getDiscussionSynthesisMessages)(formattedMessages, effectivePrompt);
+        const response = await this.llm.generateResponse([
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userPrompt },
+        ], { ...(0, zod_1.zodResponseFormat)(prompts_1.DiscussionSynthesisSchema, "DiscussionSynthesis") }, [], false);
+        //
+        // Parser la réponse
+        const parsedResponse = (res) => {
+            try {
+                if (typeof res === 'object')
+                    return res;
+                const cleanResponse = (0, prompts_1.removeCodeBlocks)(res);
+                return JSON.parse(cleanResponse);
+            }
+            catch (e) {
+                console.error("Failed to parse synthesis from LLM response:", res, e);
+                return { title: "Sans titre", summary: "" };
+            }
+        };
+        const { title: llmTitle, summary } = parsedResponse(response);
+        //
+        // En mode merge, conserver le titre existant (chargé depuis le store ou fourni par metadata)
+        const title = (existingMemoryId && (existingTitle || metadata?.title))
+            ? (existingTitle || metadata.title)
+            : llmTitle;
+        //
+        // Nettoyage du summary : trim + lignes vides
+        // L'idempotence est assurée par le prompt (règles d'extraction + merge)
+        const filteredSummary = summary
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0)
+            .join("\n");
+        if (!filteredSummary) {
+            console.warn("-- ⚠️ Empty summary from LLM, skipping memory creation/update");
+            return { results: [] };
+        }
+        //
+        // Créer l'embedding sur le title
+        const embedding = await this.embedder.embed(title);
+        //
+        // Préparer les métadonnées
+        const memoryType = metadata.type || 'discussion';
+        const applyMode = metadata.applyMode || types_1.DEFAULT_MEMORY_APPLY_MODE;
+        const memoryMetadata = {
+            ...metadata,
+            title,
+            type: memoryType,
+            applyMode,
+            userId,
+        };
+        //
+        // UPDATE si existingMemoryId fourni, sinon CREATE
+        if (existingMemoryId) {
+            await this.updateMemory(existingMemoryId, filteredSummary, { [filteredSummary]: embedding }, memoryMetadata, userId);
+            return {
+                results: [{
+                        id: existingMemoryId,
+                        memory: filteredSummary,
+                        type: memoryType,
+                        metadata: { title, event: "UPDATE" },
+                    }],
+            };
+        }
+        //
+        // CREATE nouvelle mémoire
+        const memoryId = await this.createMemory(filteredSummary, { [filteredSummary]: embedding }, memoryMetadata, userId);
+        console.log(`-- 🧠 Memory created: "${title}" (${memoryType})`);
+        return {
+            results: [{
+                    id: memoryId,
+                    memory: filteredSummary,
+                    type: memoryType,
+                    metadata: { title, event: "ADD" },
+                }],
+        };
+    }
     async get(memoryId, userId) {
         const vectorStore = await this.getVectorStore(userId);
         const memory = await vectorStore.get(memoryId);

package/dist/memory/memory.types.d.ts

@@ -9,6 +9,8 @@ export interface AddMemoryOptions extends Entity {
     metadata?: Record<string, any>;
     filters?: SearchFilters;
     capturePrompt?: string;
+    existingMemoryId?: string;
+    existingContent?: string;
 }
 export interface SearchMemoryOptions extends Entity {
     limit?: number;