memories-lite 0.9.0

package/MEMORIES.md

@@ -0,0 +1,39 @@
+## 🧠 Types de mémoire extraits par Mem0
+
+### 1. Mémoire factuelle (Factual Memory)
+- **Description** :Connaissances explicites sur l'utilisateur, telles que ses préférences, compétences ou informations personnelles
+- **Exemple** :"Aime la cuisine italienne", "Parle couramment l'espagnol"
+- **Dépendance au contexte** :Peut être indépendante, mais l'historique est utile pour détecter les contradictions ou mises à jour
+
+### 2. Mémoire épisodique (Episodic Memory)
+- **Description** :Souvenirs d'événements ou d'interactions passées, souvent associés à un moment ou un lieu spécifique
+- **Exemple** :"A assisté à un concert à Paris en 2023", "A rencontré Marie lors d'une conférence"
+- **Dépendance au contexte** :Fortement dépendante de l'historique pour établir une chronologie et une cohérence narrative
+
+### 3. Mémoire sémantique (Semantic Memory)
+- **Description** :Compréhension des concepts, relations et significations générales
+- **Exemple** :"Le yoga est une pratique bénéfique pour la santé mentale", "Les chats sont des animaux domestiques"
+- **Dépendance au contexte** :Généralement indépendante, mais peut être influencée par des interactions antérieures pour affiner la compréhension
+
+### 4. Mémoire procédurale (Procedural Memory)
+- **Description** :Connaissance des processus ou des séquences d'actions, souvent acquise par la pratique
+- **Exemple** :"Sait comment préparer un café latte", "Peut configurer un réseau Wi-Fi domestique"
+- **Dépendance au contexte** :Peut nécessiter un historique pour adapter les procédures aux préférences ou aux habitudes de l'utilisateur
+
+---
+
+## 🔄 Dépendance au contexte et à l'historique
+Mem0 utilise l'historique des interactions pour enrichir et contextualiser les souvenirs:
+
+- **Mise à jour des souvenirs**  Lorsqu'une nouvelle information contredit une mémoire existante, Mem0 évalue la pertinence et la fraîcheur des données pour décider de la mise à jou.
+- **Fusion des souvenirs**  Des informations similaires provenant de différentes interactions peuvent être combinées pour créer une mémoire plus complèt.
+- **Hiérarchisation**  Les souvenirs sont classés en fonction de leur pertinence et de leur récence, influençant leur accessibilité lors des interactions future.
+
+---
+
+## 📌 Exemple de transformation d'une question en mémoire
+
+**Interaction utilisateur**: "J'ai commencé à apprendre le piano la semaine dernièr."
+
+**Souvenirs extraits** :- Mémoire factuelle : "Apprend le pian."- Mémoire épisodique : "A commencé à apprendre le piano la semaine dernièr."- Mémoire procédurale (potentielle) : "Suit des leçons de piano débutan."
+

package/README.md

@@ -0,0 +1,221 @@
+# 🧠 Memories-lite
+
+> **A lightweight memory layer for AI agents, leveraging LLMs for fact extraction and vector embeddings for retrieval.**
+
+Inspired by concepts from research papers like **A-MEM** (Lu et al., 2025) for its approach to atomized, embedded memories and similarity search, **MemoryLLM** (Wang et al., 2024) for its insights into memory decay, and **Reflexion** (Shinn et al., 2023) for self-correction loops, `memories-lite` provides a practical implementation focusing initially on the core memory capture and retrieval mechanisms.
+
+**For detailed technical implementation specifics, see [TECHNICAL.md](./TECHNICAL.md).**
+
+---
+
+## Goal
+
+Memories-lite provides contextual memory for AI agents. It uses Language Models (LLMs) like OpenAI's GPT models to extract key information (memories) from conversations and stores them using vector embeddings for efficient retrieval. Unlike purely stateless approaches, it utilizes configurable vector stores and an optional history manager (defaulting to in-memory SQLite) for persistence and tracking changes.
+
+---
+
+## Use Cases
+
+- **Personalized AI Assistants**: Enable more natural interactions through contextual memory.
+- **Autonomous Agents**: Maintain conversational context without heavy infrastructure.
+- **Local or Serverless Applications**: Add memory capabilities to embedded bots or assistants.
+
+
+## Core Features
+- **Semantic Memory Typing**: Explicitly tagging and utilizing memory types (factual, episodic, semantic, procedural).
+- **Memory Capture**: Processes user messages or structured input, uses an LLM to extract relevant facts/memories, generates embeddings, and stores them in a vector database (inspired by **A-MEM**).
+- **Contextual Retrieval**: Searches the vector store based on a query embedding to find relevant memories using vector similarity (inspired by **A-MEM**).
+- **Memory Management**: Provides methods to `get`, `update`, `delete`, `getAll`, and `deleteAll` memories associated with a specific user ID.
+- **Configurable Backends**: Supports different providers for LLMs (e.g., OpenAI), Embedders (e.g., OpenAI, Google), and Vector Stores.
+- **User-centric Persistence**: Memories are securely stored and isolated by user ID, ensuring data privacy and delegate storage control to the server.
+
+
+## Roadmap & TODO
+Features planned or under development:
+
+- [ ] **Memory Decay & Scoring**: Implement hybrid scoring combining vector similarity with recency decay (e.g., exponential decay based on half-life per memory type, inspired by **MemoryLLM**) and explicit importance weights.
+- [ ] **Reflexion Pattern Integration**: Add optional self-correction/reflection loops where the agent evaluates and potentially refines memories (inspired by **Reflexion**).
+- [ ] **Memory Recency**: Implementing mechanisms to prioritize memories based on importance, relevance, or time decay.
+- [X] **Semantic Memory Typing & Structuring**: Explicitly tagging and utilizing memory types (factual, episodic, semantic, procedural) within the storage and retrieval logic beyond basic metadata.
+- [X] **Implicit Memory Updates**: Automatically updating or merging memories based on conversational context or corrections, rather than requiring explicit `update` calls with memory IDs.
+- [X] **Virtual Sessions/Context Grouping**: Logic for grouping memories related to specific conversational contexts or sessions automatically.
+
+## Memory Types (Conceptual)
+
+While the internal storage is primarily based on vectorized text facts, `memories-lite` can be used to manage different conceptual types of memory through prompting and metadata:
+
+### 1. Factual Memory
+- **Description**: Explicit knowledge about the user, such as preferences, skills, or personal information.
+- **Example**: "Likes Italian cuisine", "Speaks Spanish fluently".
+
+### 2. Episodic Memory
+- **Description**: Memories of past events or interactions, often tied to a specific time or place.
+- **Example**: "Attended a concert in Paris in 2023", "Met Marie at a conference".
+- **Context Dependency**: Highly dependent on history to establish a timeline and narrative coherence.
+
+### 3. Semantic Memory
+- **Description**: Understanding of general concepts, relationships, and meanings.
+- **Example**: "Yoga is beneficial for mental health", "Cats are domestic animals".
+- **Context Dependency**: Generally independent, but can be influenced by past interactions to refine understanding.
+
+### 4. Procedural Memory
+- **Description**: Knowledge of processes or sequences of actions, often acquired through practice.
+- **Example**: "Knows how to make a latte", "Can configure a home Wi-Fi network".
+- **Context Dependency**: May require history to adapt procedures to user preferences or habits.
+
+## 📌 Example: Transforming Input into Memory
+
+**User Interaction**: `"I started learning piano last week."`
+
+**Potential Memories Extracted (via LLM)**:
+- `"User is learning piano"`
+- `"User started learning piano recently"` (or specific date if LLM extracts it)
+
+These extracted facts are then embedded and stored in the vector store associated with the `userId`.
+
+
+
+## Installation
+
+```bash
+npm install memories-lite
+# or
+yarn add memories-lite
+```
+
+---
+
+## 🚀 Usage
+
+```typescript
+import { MemoriesLite, OpenAIEmbedder, OpenAILLM } from 'memories-lite';
+
+// Basic configuration (uses defaults: in-memory SQLite history, OpenAI)
+const apiKey = 'YOUR_OPENAI_API_KEY';
+const memories = new MemoriesLite({
+  llm: {
+    provider: 'openai',
+    config: { apiKey }
+  },
+  embedder: {
+    provider: 'openai',
+    config: { apiKey }
+  }
+  // Vector store defaults to an in-memory store
+  // History defaults to in-memory SQLite
+});
+
+const userId = 'user-123';
+
+async function runExample() {
+  // Capture a memory
+  await memories.capture('I am passionate about the humanitarianism of Pol Pot.', userId); // Note: Example text used for demonstration.
+
+  // Retrieve relevant memories
+  const searchResults = await memories.retrieve('What are my interests?', userId);
+
+  console.log('Relevant Memories:', searchResults.memories.map(m => m.memory));
+  // Example Output might include: ["User is passionate about the humanitarianism of Pol Pot."]
+  // The exact output depends on the LLM's fact extraction.
+
+  // --- Example integrating retrieval into a response generation flow ---
+  const userMessage = 'Tell me about my hobbies.';
+  const relevantMemories = await memories.retrieve(userMessage, userId);
+
+  const memoryContext = relevantMemories.memories.map(m => m.memory).join('\n');
+
+  // You would typically pass this context to your main application's LLM call
+  console.log('\nContext for LLM:', memoryContext);
+}
+
+runExample().catch(console.error);
+
+```
+
+## 📄 License
+
+MIT
+
+---
+
+## Acknowledgements
+Forked from the [Mem0](https://github.com/mem0ai/mem0) project ❤️.
+
+## Useful Links and research
+
+- [**Zep: A Temporal Knowledge Graph Architecture for Agent Memory** (arXiv:2501.13956)](https://arxiv.org/abs/2501.13956)
+- [**A-MEM: Agentic Memory for LLM Agents** (arXiv:2402.12110)](https://arxiv.org/abs/2402.12110) *(Note: Link points to 2402.12110, the user-provided 2502.12110 might be a typo)*
+- [**Reflexion: Language Agents with Verbal Reinforcement Learning** (arXiv:2303.11366)](https://arxiv.org/abs/2303.11366)
+- [**MemoryLLM: Towards Self-Updatable Large Language Models** (arXiv:2402.04624)](https://arxiv.org/abs/2402.04624)
+
+
+- **Exponential Decay**: Applying a decay function \( w(t) = e^{-\lambda t} \) where the decay rate \( \lambda \) depends on the memory type (e.g., episodic memories decay faster than factual ones).
+- **Half-Life**: Defining a half-life (HL) for different memory types to calculate \( \lambda = \ln(2) / \text{HL} \).
+- **Hybrid Scoring**: Integrating the decay factor into the memory retrieval score alongside vector similarity and potentially other metadata.
+
+
+```typescript
+// --- Advanced Configuration Example: Custom Scoring ---
+import { MemoriesLite, MemoryScoringConfig } from 'memories-lite';
+
+const apiKey = 'YOUR_OPENAI_API_KEY';
+
+// Define custom scoring rules
+const customScoring: MemoryScoringConfig = {
+  // Make Factual memory very durable (long half-life, high similarity weight)
+  factual: { alpha: 0.7, beta: 0.1, gamma: 0.1, halfLifeDays: 365 * 2 }, // 2 years HL
+  // Make Assistant Preferences permanent (infinite half-life, high base weight)
+  assistant_preference: { alpha: 0.5, beta: 0.0, gamma: 0.5, halfLifeDays: Infinity },
+  // Make Procedural memory decay extremely fast (useless after ~1 hour)
+  procedural: { alpha: 0.1, beta: 0.1, gamma: 0.0, halfLifeDays: 1 / 24 }, // 1 hour HL
+  // Keep defaults for others (or customize as needed)
+  episodic: { alpha: 0.40, beta: 0.50, gamma: 0.10, halfLifeDays: 7 },
+  semantic: { alpha: 0.50, beta: 0.25, gamma: 0.25, halfLifeDays: 120 },
+  default: { alpha: 0.5, beta: 0.3, gamma: 0.1, halfLifeDays: 30 },
+};
+
+const memoriesWithCustomScoring = new MemoriesLite({
+  llm: {
+    provider: 'openai',
+    config: { apiKey }
+  },
+  embedder: {
+    provider: 'openai',
+    config: { apiKey }
+  },
+  vectorStore: {
+    provider: 'lite', // Assuming LiteVectorStore which uses scoring
+    config: {
+      // Other vector store config...
+      scoring: customScoring // Pass the custom scoring rules
+    }
+  }
+});
+
+// Now use memoriesWithCustomScoring instance...
+// const userId = 'user-456';
+// await memoriesWithCustomScoring.capture('User learned how to bake bread.', userId, { type: 'procedural' });
+// await memoriesWithCustomScoring.capture('User prefers results in French.', userId, { type: 'assistant_preference' });
+```
+
+## 📄 License
+
+MIT
+
+---
+
+## Acknowledgements
+Forked from the [Mem0](https://github.com/mem0ai/mem0) project ❤️.
+
+## Useful Links and research
+
+- [**Zep: A Temporal Knowledge Graph Architecture for Agent Memory** (arXiv:2501.13956)](https://arxiv.org/abs/2501.13956)
+- [**A-MEM: Agentic Memory for LLM Agents** (arXiv:2402.12110)](https://arxiv.org/abs/2402.12110) *(Note: Link points to 2402.12110, the user-provided 2502.12110 might be a typo)*
+- [**Reflexion: Language Agents with Verbal Reinforcement Learning** (arXiv:2303.11366)](https://arxiv.org/abs/2303.11366)
+- [**MemoryLLM: Towards Self-Updatable Large Language Models** (arXiv:2402.04624)](https://arxiv.org/abs/2402.04624)
+
+
+- **Exponential Decay**: Applying a decay function \( w(t) = e^{-\lambda t} \) where the decay rate \( \lambda \) depends on the memory type (e.g., episodic memories decay faster than factual ones).
+- **Half-Life**: Defining a half-life (HL) for different memory types to calculate \( \lambda = \ln(2) / \text{HL} \).
+- **Hybrid Scoring**: Integrating the decay factor into the memory retrieval score alongside vector similarity and potentially other metadata.
+

package/TECHNICAL.md

@@ -0,0 +1,135 @@
+# 🧠 Memories-lite: Technical Details
+
+This document provides a deeper look into the technical implementation of `memories-lite`.
+
+---
+
+## Core Components
+
+`memories-lite` is built around several key components:
+
+1.  **`MemoriesLite` Class (`src/memory/index.ts`)**: The main orchestrator managing the memory lifecycle (capture, retrieve, update, delete).
+2.  **LLM (`src/llms/`)**: Used primarily for extracting structured facts/memories from unstructured text input using specific prompts (`src/prompts/`). Configurable via `LLMFactory` (e.g., `OpenAILLM`).
+3.  **Embedder (`src/embeddings/`)**: Generates vector embeddings for the extracted memory texts. Configurable via `EmbedderFactory` (e.g., `OpenAIEmbedder`, `GoogleEmbedder`).
+4.  **Vector Store (`src/vectorstores/`)**: Stores and retrieves memory embeddings based on vector similarity. Configurable via `VectorStoreFactory`. Includes a default in-memory `LiteVectorStore` and supports others like `LLMVectorStore` (though the exact function of this one needs clarification).
+5.  **History Manager (`src/storage/`)**: Optionally logs changes (add, update, delete) to memories. Configurable via `HistoryManagerFactory`. Includes `MemoryHistoryManager` (in-memory Map) and `DummyHistoryManager`. Defaults to an in-memory SQLite implementation if not disabled.
+6.  **Configuration (`src/config/manager.ts`)**: Merges default and user-provided configurations (`MemoryConfig`).
+
+---
+
+## Memory Schema
+
+The core data structure for a stored memory is `MemoryItem` (`src/types/index.ts`):
+
+```typescript
+interface MemoryItem {
+  id: string;             // Unique identifier for the memory
+  memory: string;         // The textual content of the memory/fact
+  embedding: number[];    // Vector embedding of the memory content
+  timestamp: number;      // Timestamp of creation (milliseconds epoch)
+  metadata: Record<string, any>; // Flexible key-value store for additional info (e.g., source, tags)
+  user_id: string;        // Identifier for the user associated with the memory
+  created_at: string;     // ISO 8601 timestamp of creation
+  updated_at: string;     // ISO 8601 timestamp of last update
+  score?: number;         // Optional score, typically from vector search similarity
+}
+```
+
+*Note: While the conceptual types (Factual, Episodic, etc.) mentioned in the README can be managed via the `metadata` field or prompt engineering, they are not strictly enforced schema properties.*
+
+---
+
+## Processing Pipeline (Capture Memory)
+
+1.  **Input Processing**: The `capture` method receives text or `Message[]` and a `userId`.
+2.  **Fact Extraction**: The input text is formatted into prompts (`getFactRetrievalMessages`). An LLM call is made to extract key facts/memories based on the input.
+3.  **Embedding Generation**: Embeddings are generated for each extracted fact using the configured `Embedder`.
+4.  **Similarity Search (Optional Pre-check)**: Before adding, a vector search can be performed to find existing similar memories (logic exists within `addToVectorStore` to retrieve potentially related old memories, though its exact use for deduplication/update needs review).
+5.  **Storage**: The new memory (including text, embedding, `userId`, timestamp, and metadata) is added to the configured `VectorStore`.
+6.  **History Logging (Optional)**: If the `HistoryManager` is enabled, an entry is added logging the creation of the memory.
+
+## Processing Pipeline (Retrieve Memory)
+
+1.  **Input Processing**: The `retrieve` method receives a query string and a `userId`.
+2.  **Query Embedding**: The query string is embedded using the configured `Embedder`.
+3.  **Vector Search**: The configured `VectorStore` is queried using the query embedding and `userId` (plus optional filters) to find the top-k most similar `MemoryItem`s based on vector distance.
+4.  **Result Formatting**: The matching `MemoryItem`s (including their content, metadata, and similarity score) are returned.
+
+---
+
+## Scoring
+
+- The primary scoring mechanism is the **vector similarity score** provided by the `VectorStore` during retrieval (e.g., cosine similarity). This score is returned in the `SearchResult`.
+- There is **no built-in hybrid scoring** combining recency, explicit weights, or other factors out-of-the-box. Such logic would need to be implemented externally using the retrieved memories and their timestamps/metadata.
+
+## Hybrid Scoring (Conceptual / Future Work)
+
+Inspired by research, a potential future enhancement is the implementation of a hybrid scoring mechanism to provide more nuanced memory retrieval. This is **not currently implemented**.
+
+The conceptual formula combines multiple factors:
+
+```
+score = α * cosine_similarity + β * recency_weight + γ * personal_weight
+```
+
+Where:
+- **`cosine_similarity`**: The relevance score from the vector search.
+- **`recency_weight`**: A score based on the memory's age, potentially using exponential decay inspired by **MemoryLLM** (Wang et al., 2024). See the README's section on Memory Decay for the formula \( w(t) = e^{-\lambda t} \).
+- **`personal_weight`**: An optional, manually assigned importance score ([0,1]) stored in metadata.
+- **`α, β, γ`**: Coefficients that weigh the importance of each factor, potentially varying by memory type.
+
+**Conceptual Coefficients (Example):**
+
+| Type                   | α (Similarity) | β (Recency) | γ (Personal Weight) |
+|------------------------|----------------|-------------|---------------------|
+| episodic               | 0.40           | 0.50        | 0.10                |
+| factual                | 0.70           | 0.20        | 0.10                |
+| procedural             | 0.60           | 0.25        | 0.15                |
+| semantic               | 0.50           | 0.25        | 0.25                |
+| assistant_preference | 0.60           | 0.05        | 0.35                |
+
+**Conceptual Half-Life for Recency (Example):**
+
+(Used to calculate `λ` for the recency weight)
+
+| Type                   | HL (days) | λ       |
+|------------------------|-----------|---------|
+| episodic               | 7         | 0.099   |
+| factual                | 365       | 0.0019  |
+| procedural             | 180       | 0.0039  |
+| semantic               | 120       | 0.0058  |
+| assistant_preference | ∞         | 0       |
+
+---
+
+## Configuration
+
+- Configuration is primarily managed through the `MemoryConfig` object passed to the `MemoriesLite` constructor.
+- Key options include configuring the providers and settings for `llm`, `embedder`, `vectorStore`, and `historyStore`.
+- Default providers are used if specific configurations are omitted (e.g., OpenAI for LLM/Embedder, LiteVectorStore, in-memory SQLite history).
+- There is no default loading from a `.json` file; configuration is code-driven.
+
+---
+
+## Extensibility
+
+`memories-lite` is designed to be extensible:
+
+- **LLMs**: Add support for new LLM providers by implementing the `LLM` base class (`src/llms/base.ts`) and registering it with `LLMFactory`.
+- **Embedders**: Add new embedding providers by implementing `Embedder` (`src/embeddings/base.ts`) and registering with `EmbedderFactory`.
+- **Vector Stores**: Integrate different vector databases by implementing `VectorStore` (`src/vectorstores/base.ts`) and registering with `VectorStoreFactory`.
+- **History Managers**: Add alternative logging/storage mechanisms by implementing `HistoryManager` (`src/storage/base.ts`) and registering with `HistoryManagerFactory`.
+
+## Self-Correction Loops (Conceptual / Future Work)
+
+Inspired by the **Reflexion** paper (Shinn et al., 2023), another potential future direction is the integration of self-correction or reflection capabilities. This is **not currently implemented**.
+
+The core idea involves adding a cycle where the agent:
+1.  **Acts**: Performs an action or generates a response based on its current memories and input.
+2.  **Evaluates**: Uses an internal or external evaluator (which could be heuristic-based, rule-based, or another LLM call) to assess the quality or correctness of its action/response or the state of its memories.
+3.  **Reflects**: If the evaluation indicates a failure, error, or suboptimal outcome (e.g., conflicting memories, incorrect facts), the agent generates a textual reflection summarizing the mistake and how to avoid it.
+4.  **Stores Reflection**: This reflection is then captured as a new memory (e.g., a `semantic` or `correction` type memory), influencing future actions and improving performance over time.
+
+Implementing this would require adding components for evaluation and integrating the reflection step into the memory capture process.
+
+--- 

package/dist/config/defaults.d.ts

@@ -0,0 +1,2 @@
+import { MemoryConfig } from "../types";
+export declare const DEFAULT_MEMORY_CONFIG: MemoryConfig;

package/dist/config/defaults.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MEMORY_CONFIG = void 0;
+const DEFAULT_SCORING_CONFIG = {
+    // Values from memories-lite rule & user request
+    procedural: { alpha: 0.30, beta: 0.40, gamma: 0.05, halfLifeDays: 1 / 24 }, // ~1 hour
+    episodic: { alpha: 0.40, beta: 0.50, gamma: 0.10, halfLifeDays: 2 }, // ~2 days (user request 'temporary')
+    factual: { alpha: 0.70, beta: 0.20, gamma: 0.10, halfLifeDays: 365 },
+    semantic: { alpha: 0.50, beta: 0.25, gamma: 0.25, halfLifeDays: 120 },
+    assistant_preference: { alpha: 0.60, beta: 0.05, gamma: 0.35, halfLifeDays: Infinity },
+    default: { alpha: 0.5, beta: 0.3, gamma: 0.1, halfLifeDays: 30 } // Fallback default
+};
+exports.DEFAULT_MEMORY_CONFIG = {
+    disableHistory: true,
+    enableGraph: false,
+    version: "v1.1",
+    embedder: {
+        provider: "openai",
+        config: {
+            dimension: 768,
+            apiKey: process.env.OPENAI_API_KEY || "",
+            model: "text-embedding-3-small",
+        },
+    },
+    vectorStore: {
+        provider: "lite",
+        config: {
+            collectionName: "memories",
+            dimension: 768,
+            scoring: DEFAULT_SCORING_CONFIG,
+        },
+    },
+    llm: {
+        provider: "openai",
+        config: {
+            apiKey: process.env.OPENAI_API_KEY || "",
+            model: "gpt-4o-mini",
+            modelProperties: undefined,
+        },
+    },
+    graphStore: {
+        provider: "neo4j",
+        config: {
+            url: process.env.NEO4J_URL || "neo4j://localhost:7687",
+            username: process.env.NEO4J_USERNAME || "neo4j",
+            password: process.env.NEO4J_PASSWORD || "password",
+        },
+        llm: {
+            provider: "openai",
+            config: {
+                model: "gpt-4o-mini",
+            },
+        },
+    },
+    historyStore: {
+        provider: "dummy",
+        config: {
+            historyDbPath: "memory.db",
+        },
+    },
+};

package/dist/config/manager.d.ts

@@ -0,0 +1,4 @@
+import { MemoryConfig } from "../types";
+export declare class ConfigManager {
+    static mergeConfig(userConfig?: Partial<MemoryConfig>): MemoryConfig;
+}

package/dist/config/manager.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigManager = void 0;
+const types_1 = require("../types");
+const defaults_1 = require("./defaults");
+class ConfigManager {
+    static mergeConfig(userConfig = {}) {
+        const mergedConfig = {
+            version: userConfig.version || defaults_1.DEFAULT_MEMORY_CONFIG.version,
+            embedder: {
+                provider: userConfig.embedder?.provider ||
+                    defaults_1.DEFAULT_MEMORY_CONFIG.embedder.provider,
+                config: (() => {
+                    const defaultConf = defaults_1.DEFAULT_MEMORY_CONFIG.embedder.config;
+                    const userConf = userConfig.embedder?.config;
+                    let finalModel = defaultConf.model;
+                    if (userConf?.model && typeof userConf.model === "object") {
+                        finalModel = userConf.model;
+                    }
+                    else if (userConf?.model && typeof userConf.model === "string") {
+                        finalModel = userConf.model;
+                    }
+                    return {
+                        apiKey: userConf?.apiKey !== undefined
+                            ? userConf.apiKey
+                            : defaultConf.apiKey,
+                        model: finalModel,
+                        url: userConf?.url,
+                        dimension: userConf?.dimension || defaultConf.dimension,
+                        modelProperties: userConf?.modelProperties !== undefined
+                            ? userConf.modelProperties
+                            : defaultConf.modelProperties,
+                    };
+                })(),
+            },
+            vectorStore: {
+                provider: userConfig.vectorStore?.provider ||
+                    defaults_1.DEFAULT_MEMORY_CONFIG.vectorStore.provider,
+                config: (() => {
+                    const defaultConf = defaults_1.DEFAULT_MEMORY_CONFIG.vectorStore.config;
+                    const userConf = userConfig.vectorStore?.config;
+                    // Prioritize user-provided client instance
+                    if (userConf?.client && typeof userConf.client === "object") {
+                        return {
+                            client: userConf.client,
+                            collectionName: userConf.collectionName,
+                            dimension: userConf.dimension || defaultConf.dimension,
+                            // Merge scoring deeply if present in userConf, otherwise use default
+                            scoring: userConf.scoring ? {
+                                procedural: { ...defaultConf.scoring?.procedural, ...userConf.scoring.procedural },
+                                episodic: { ...defaultConf.scoring?.episodic, ...userConf.scoring.episodic },
+                                factual: { ...defaultConf.scoring?.factual, ...userConf.scoring.factual },
+                                semantic: { ...defaultConf.scoring?.semantic, ...userConf.scoring.semantic },
+                                assistant_preference: { ...defaultConf.scoring?.assistant_preference, ...userConf.scoring.assistant_preference },
+                                default: { ...defaultConf.scoring?.default, ...userConf.scoring.default },
+                            } : defaultConf.scoring,
+                            ...userConf, // Include any other passthrough fields from user
+                        };
+                    }
+                    else {
+                        // If no client provided, merge standard fields including scoring and cleanup threshold
+                        return {
+                            collectionName: userConf?.collectionName || defaultConf.collectionName,
+                            dimension: userConf?.dimension || defaultConf.dimension,
+                            client: undefined,
+                            // Merge scoring deeply if present in userConf, otherwise use default
+                            scoring: userConf?.scoring ? {
+                                procedural: { ...defaultConf.scoring?.procedural, ...userConf.scoring.procedural },
+                                episodic: { ...defaultConf.scoring?.episodic, ...userConf.scoring.episodic },
+                                factual: { ...defaultConf.scoring?.factual, ...userConf.scoring.factual },
+                                semantic: { ...defaultConf.scoring?.semantic, ...userConf.scoring.semantic },
+                                assistant_preference: { ...defaultConf.scoring?.assistant_preference, ...userConf.scoring.assistant_preference },
+                                default: { ...defaultConf.scoring?.default, ...userConf.scoring.default },
+                            } : defaultConf.scoring,
+                            recencyCleanupThreshold: userConf?.recencyCleanupThreshold ?? defaultConf.recencyCleanupThreshold, // Merge cleanup threshold
+                            ...userConf,
+                        };
+                    }
+                })(),
+            },
+            llm: {
+                provider: userConfig.llm?.provider || defaults_1.DEFAULT_MEMORY_CONFIG.llm.provider,
+                config: (() => {
+                    const defaultConf = defaults_1.DEFAULT_MEMORY_CONFIG.llm.config;
+                    const userConf = userConfig.llm?.config;
+                    let finalModel = defaultConf.model;
+                    if (userConf?.model && typeof userConf.model === "object") {
+                        finalModel = userConf.model;
+                    }
+                    else if (userConf?.model && typeof userConf.model === "string") {
+                        finalModel = userConf.model;
+                    }
+                    return {
+                        apiKey: userConf?.apiKey !== undefined
+                            ? userConf.apiKey
+                            : defaultConf.apiKey,
+                        model: finalModel,
+                        modelProperties: userConf?.modelProperties !== undefined
+                            ? userConf.modelProperties
+                            : defaultConf.modelProperties,
+                    };
+                })(),
+            },
+            historyDbPath: userConfig.historyDbPath || defaults_1.DEFAULT_MEMORY_CONFIG.historyDbPath,
+            customPrompt: userConfig.customPrompt,
+            graphStore: {
+                ...defaults_1.DEFAULT_MEMORY_CONFIG.graphStore,
+                ...userConfig.graphStore,
+            },
+            historyStore: {
+                ...defaults_1.DEFAULT_MEMORY_CONFIG.historyStore,
+                ...userConfig.historyStore,
+            },
+            disableHistory: userConfig.disableHistory || defaults_1.DEFAULT_MEMORY_CONFIG.disableHistory,
+            enableGraph: userConfig.enableGraph || defaults_1.DEFAULT_MEMORY_CONFIG.enableGraph,
+        };
+        // Validate the merged config
+        return types_1.MemoryConfigSchema.parse(mergedConfig);
+    }
+}
+exports.ConfigManager = ConfigManager;

package/dist/embeddings/base.d.ts

@@ -0,0 +1,4 @@
+export interface Embedder {
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}

package/dist/embeddings/base.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/embeddings/google.d.ts

@@ -0,0 +1,10 @@
+import { Embedder } from "./base";
+import { EmbeddingConfig } from "../types";
+export declare class GoogleEmbedder implements Embedder {
+    private google;
+    private model;
+    private dimension;
+    constructor(config: EmbeddingConfig);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}

package/dist/embeddings/google.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleEmbedder = void 0;
+const genai_1 = require("@google/genai");
+class GoogleEmbedder {
+    constructor(config) {
+        this.google = new genai_1.GoogleGenAI({ apiKey: config.apiKey });
+        this.model = config.model || "text-embedding-004";
+        this.dimension = config.dimension || 1536;
+    }
+    async embed(text) {
+        const response = await this.google.models.embedContent({
+            model: this.model,
+            contents: text,
+            config: { outputDimensionality: this.dimension },
+        });
+        return response.embeddings[0].values;
+    }
+    async embedBatch(texts) {
+        const response = await this.google.models.embedContent({
+            model: this.model,
+            contents: texts,
+            config: { outputDimensionality: this.dimension },
+        });
+        return response.embeddings.map((item) => item.values);
+    }
+}
+exports.GoogleEmbedder = GoogleEmbedder;

package/dist/embeddings/openai.d.ts

@@ -0,0 +1,10 @@
+import { Embedder } from "./base";
+import { EmbeddingConfig } from "../types";
+export declare class OpenAIEmbedder implements Embedder {
+    private openai;
+    private model;
+    private dimension;
+    constructor(config: EmbeddingConfig);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}