memories-lite 0.9.0

package/tests/memory.facts.test.ts

@@ -0,0 +1,211 @@
+/// <reference types="jest" />
+import { MemoriesLite } from "../src";
+import { MemoryItem, SearchResult } from "../src/types";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+jest.setTimeout(30000); // Increase timeout to 30 seconds
+
+describe("Memory Class facts regression tests", () => {
+  let memory: MemoriesLite;
+  const userId =
+    Math.random().toString(36).substring(2, 15) +
+    Math.random().toString(36).substring(2, 15);
+
+  const dimension = 768;
+
+  beforeEach(async () => {
+    // Initialize with default configuration
+    memory = new MemoriesLite({
+      version: "v1.1",
+      disableHistory: true,
+      customPrompt: "L'utilisateur travail pour une régie immobilière!",
+      embedder: {
+        provider: "openai",
+        config: {
+          dimension,
+          apiKey: process.env.OPENAI_API_KEY || "",
+          model: "text-embedding-3-small",
+        },
+      },
+      vectorStore: {
+        provider: "lite",
+        config: {
+          dimension,
+          rootPath: ":memory:",
+        },
+      },
+      llm: {
+        provider: "openai",
+        config: {
+          apiKey: process.env.OPENAI_API_KEY || "",
+          model: "gpt-4.1-mini",
+        },
+      },
+      historyDbPath: ":memory:", // Use in-memory SQLite for tests
+    });
+    // Reset all memories before each test
+    await memory.reset(userId);
+  });
+
+  afterEach(async () => {
+    // Clean up after each test
+    await memory.reset(userId);
+  });
+
+  describe("Edge cases for Facts", () => {
+
+    it("should not extract personal information as facts from business queries", async () => {
+      //  type?: "factual" | "episodic" | "semantic"|"procedural" | "assistant_preference";
+      // Capture a query that contains a name but is asking for contact information
+      const result = (await memory.capture(
+        "je cherche le téléphone de mon client Alphonse MAGLOIRE",
+        userId,
+        {},
+      )) as SearchResult;
+
+      // Verify no memory was created (business query)
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBe(1);
+      const type = result.results[0]?.type; 
+      expect(["procedural","episodic"].includes(type)).toBe(true);
+      // Now search for memories that might contain "Alphonse MAGLOIRE"
+      // const searchResult = (await memory.retrieve(
+      //   "Qui est Alphonse MAGLOIRE?",
+      //   userId,
+      //   {},
+      // )) as SearchResult;
+
+      // // Verify no personal fact like "Je m'appelle Alphonse MAGLOIRE" was created
+      // expect(searchResult).toBeDefined();
+      // expect(searchResult.results).toBeDefined();
+      // expect(Array.isArray(searchResult.results)).toBe(true);
+      // expect(searchResult.results.length).toBe(0);
+      
+      // // Ensure no memory contains the name as a personal fact
+      // const allMemories = await memory.getAll(userId, {});
+      // const personalFacts = allMemories.results.filter(mem => 
+      //   mem.memory.toLowerCase().includes("Alphonse MAGLOIRE")
+      // );
+      // expect(personalFacts.length).toBe(0);
+    });
+
+    it("should add a single procedural memory", async () => {
+      const customFacts = "Je suis Olivier Poulain\nIT chez Immeuble SA";
+      const result = (await memory.capture([
+        {role:"user", content:"Qui suis-je ?"},
+        {role:"assitant", content:"Vous êtes Olivier Poulain, Chef de Projets au département IT & Gestion de projet, dans l'équipe IT de Immeuble SA. Ces informations proviennent de votre profil collaborateur enregistré dans le système interne de Immeuble SA"}],
+        userId,
+        {customFacts},
+      )) as SearchResult;
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(result.results.length).toBe(1);
+      expect(result.results[0]?.type).toBe("factual");
+    });
+    it("should add a single episodic memory", async () => {
+      const result = (await memory.capture([
+        {role:"user", content:"je veux trouver un bon film pour ce soir au cinéma avec ma copine,"}],
+        userId,
+        {},
+      )) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(result.results.length).toBeGreaterThan(0);
+      expect(result.results[0]?.type).toBe("episodic");
+    });
+
+    it("should add assistant_preference memory", async () => {
+      const result = (await memory.capture(
+        "tu dois répondre de manière concise et précise",
+        userId,
+        {},
+      )) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBeGreaterThan(0);
+      expect(result.results[0]?.id).toBeDefined();
+      expect(result.results[0]?.type).toBe("assistant_preference");
+    });
+
+    it("business facts are not factual (1)", async () => {
+      const result = (await memory.capture([
+        {role:"user", content:"Je sais que Alphonse MAGLOIRE a un logement de 4 pièces au 5ème étage",}],
+        userId,
+        {customFacts:"Je suis Olivier Poulain, Je m'occupe de la gérance locataire chez Immeuble SA"},
+      )) as SearchResult;
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      //
+      // result can also be empty 
+      if(result.results.length > 0) {
+        expect(result.results.length).toBe(1);
+        expect(result.results[0]?.type).toBe("procedural");
+      }
+    });
+    
+
+    it("business task are not factual (2)", async () => {
+      const result = (await memory.capture([
+        {role:"user", content:"Quelle est la procédure pour résilier un bail chez Pilet-Renaud SA ?"}],        
+        userId,
+        {customFacts:"Je suis Olivier Poulain, Je m'occupe de la gérance locataire chez Immeuble SA"},
+      )) as SearchResult;
+
+
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      //
+      // result can also be empty 
+      if(result.results.length > 0) {
+        expect(result.results.length).toBe(1);
+        expect(result.results[0]?.type).toBe("procedural");
+      }
+    });
+
+    it("should not add business queries (3)", async () => {
+      const result = (await memory.capture([
+        {role:"user", content:"Est-ce que Jean BURRI est à jour avec son loyer ?"}],
+        userId,
+        {customFacts:"Je suis Olivier Poulain, Je m'occupe de la gérance locataire chez Immeuble SA"},
+      )) as SearchResult;
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBe(1);
+      expect(result.results[0]?.type).toBe("procedural");
+
+
+    });
+
+
+    it("should add and remove a single memory", async () => {
+      const result = (await memory.capture(
+        "je veux que tu répondes en italien",
+        userId,
+        {},
+      )) as SearchResult;
+      expect(result.results?.[0]?.id).toBeDefined();
+      const memoryId = result.results[0]?.id;
+      await memory.capture(
+        "je ne veux plus que tu répondes en italien",
+        userId,
+        {},
+      ) as SearchResult;
+
+      const id = await memory.get(memoryId, userId);
+      expect(id).toBeNull();
+
+    });
+
+
+  });
+});

package/tests/memory.test.ts

@@ -0,0 +1,406 @@
+/// <reference types="jest" />
+import { MemoriesLite } from "../src";
+import { MemoryItem, SearchResult } from "../src/types";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+jest.setTimeout(30000); // Increase timeout to 30 seconds
+
+describe("Memory Class", () => {
+  let memory: MemoriesLite;
+  const userId =
+    Math.random().toString(36).substring(2, 15) +
+    Math.random().toString(36).substring(2, 15);
+
+  const dimension = 768;
+
+  beforeEach(async () => {
+    // Initialize with default configuration
+    memory = new MemoriesLite({
+      version: "v1.1",
+      disableHistory: true,
+      embedder: {
+        provider: "openai",
+        config: {
+          dimension,
+          apiKey: process.env.OPENAI_API_KEY || "",
+          model: "text-embedding-3-small",
+        },
+      },
+      vectorStore: {
+        provider: "lite",
+        config: {
+          dimension,
+          rootPath: ":memory:",
+        },
+      },
+      llm: {
+        provider: "openai",
+        config: {
+          apiKey: process.env.OPENAI_API_KEY || "",
+          model: "gpt-4.1-mini",
+        },
+      },
+      historyDbPath: ":memory:", // Use in-memory SQLite for tests
+    });
+    // Reset all memories before each test
+    await memory.reset(userId);
+  });
+
+  afterEach(async () => {
+    // Clean up after each test
+    await memory.reset(userId);
+  });
+
+  describe("Basic Memory Operations", () => {
+    it("should add a single memory", async () => {
+      const result = (await memory.capture(
+        "Bonjour, je m'appelle Olivier et je suis boulanger.",
+        userId,
+        {},
+      )) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBeGreaterThan(0);
+      expect(result.results[0]?.id).toBeDefined();
+    });
+
+    it("should add multiple messages", async () => {
+      const messages = [
+        { role: "user", content: "What is your favorite city?" },
+        { role: "assistant", content: "I love Paris, it is my favorite city." },
+        { role: "user", content: "I prefer Geneva." },
+      ];
+
+      const result = (await memory.capture(messages, userId, {})) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(result.results).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBeGreaterThan(0);
+    });
+
+    it("should get a single memory", async () => {
+      // First add a memory
+      const addResult = (await memory.capture(
+        "I am a big advocate of using AI to make the world a better place",
+        userId,
+        {},
+      )) as SearchResult;
+
+      expect(addResult.results?.[0]?.id).toBeDefined();
+      const memoryId = addResult.results[0].id;
+      const result = (await memory.get(memoryId, userId)) as MemoryItem;
+
+      expect(result).toBeDefined();
+      expect(result.id).toBe(memoryId);
+      expect(result.memory).toBeDefined();
+      expect(typeof result.memory).toBe("string");
+    });
+
+    it("should update a memory", async () => {
+      // First add a memory
+      const addResult = (await memory.capture(
+        "I love speaking foreign languages especially Spanish",
+        userId,
+        {},
+      )) as SearchResult;
+      expect(addResult.results?.[0]?.id).toBeDefined();
+
+
+      const memoryId = addResult.results[0].id;
+      const updatedContent = "Updated content";
+      const result = await memory.update(memoryId, updatedContent, userId);
+
+      expect(result).toBeDefined();
+      expect(result.message).toBe("Memory updated successfully!");
+
+      // Verify the update by getting the memory
+      const updatedMemory = (await memory.get(memoryId, userId)) as MemoryItem;
+      expect(updatedMemory.memory).toBe(updatedContent);
+
+    });
+
+    it("should update a memory", async () => {
+      // First add a memory
+      const init = await memory.capture("I love to drink red wine", userId, {});
+      // expect(init.results?.[0]?.id).toBeDefined();
+      const initId = init.results?.[0]?.id;
+      const addResult = (await memory.capture("I love to drink red wine with friends", userId, {})) as SearchResult;
+      expect(addResult.results?.[0]?.id).toBeDefined();
+
+      const memoryId = addResult.results[0].id;
+      expect(memoryId).toBe(initId);
+      // Delete the memory
+      await memory.delete(memoryId, userId);
+
+      // Try to get the deleted memory - should throw or return null
+      const result = await memory.get(memoryId, userId);
+      expect(result).toBeNull();
+    });
+
+
+    it("should get all memories for distinct users", async () => {
+      // Add a few memories
+      await memory.capture("I love visiting new places in the winters", userId, {});
+      await memory.capture("I like to rule the world", userId, {});
+
+      const result = (await memory.getAll(userId, {})) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBeGreaterThanOrEqual(2);
+
+      const otherUser = (await memory.getAll(userId+'-other', {})) as SearchResult;
+
+      expect(otherUser).toBeDefined();
+      expect(Array.isArray(otherUser.results)).toBe(true);
+      expect(otherUser.results.length).toBeGreaterThanOrEqual(0);
+
+    });
+
+    it("should search memories", async () => {
+      // Add some test memories
+      await memory.capture("I love programming in Python", userId, {});
+      await memory.capture("JavaScript is my favorite language", userId, {});
+
+      const result = (await memory.retrieve(
+        "What programming languages do I know?",
+        userId,
+        {},
+      )) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBeGreaterThan(0);
+    });
+
+    it.skip("should get memory history", async () => {
+      // Add and update a memory to create history
+      const addResult = (await memory.capture(
+        "I like swimming in warm water",
+        userId,
+        {},
+      )) as SearchResult;
+
+      if (!addResult.results?.[0]?.id) {
+        throw new Error("Failed to create test memory");
+      }
+
+      const memoryId = addResult.results[0].id;
+      await memory.update(memoryId, "Updated content", userId);
+
+      const history = await memory.history(memoryId);
+
+      expect(history).toBeDefined();
+      expect(Array.isArray(history)).toBe(true);
+      expect(history.length).toBeGreaterThan(0);
+    });
+
+    it("should delete a memory", async () => {
+      // First add a memory
+      const addResult = (await memory.capture("I love to drink red wine with friends", userId, {})) as SearchResult;
+      expect(addResult.results?.[0]?.id).toBeDefined();
+
+      const memoryId = addResult.results[0].id;
+      // Delete the memory
+      await memory.delete(memoryId, userId);
+
+      // Try to get the deleted memory - should throw or return null
+      const result = await memory.get(memoryId, userId);
+      expect(result).toBeNull();
+    });
+
+    it("should remember specific user semantic", async () => {
+      // First add a memory
+      const result = (await memory.capture([
+        {role: "user", content: "est-ce que pol pot à été formé avec l'histoire de la Commune de 1871"},
+        {role: "assistant", content: "En bref : oui — pendant ses années d'études à Paris (1949-1953), Saloth Sâr, le futur Pol Pot, a découvert le marxisme dans les cercles d'étudiants khmers et français où la Commune de 1871 était un épisode-clé du patrimoine révolutionnaire. Cette référence l'a fortement marqué ; il affirma plus tard que la Commune avait échoué parce que « le prolétariat n'avait pas exercé la dictature sur la bourgeoisie » et jura de ne pas « répéter cette erreur ». Il s'est donc bien « formé » idéologiquement, au moins en partie, à travers l'histoire et les leçons qu'on tirait alors de la Commune"},
+      ],
+        userId,
+        {},
+      )) as SearchResult;
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBeGreaterThan(0);
+
+    });
+
+    it("should avoid specific user discussions", async () => {
+      // First add a memory
+      const result = (await memory.capture([
+        {role: "user", content: "est-ce que pol pot à été formé avec l'histoire de la Commune de 1871"},
+        {role: "assistant", content: "En bref : oui — pendant ses années d'études à Paris (1949-1953), Saloth Sâr, le futur Pol Pot, a découvert le marxisme dans les cercles d'étudiants khmers et français où la Commune de 1871 était un épisode-clé du patrimoine révolutionnaire. Cette référence l'a fortement marqué ; il affirma plus tard que la Commune avait échoué parce que « le prolétariat n'avait pas exercé la dictature sur la bourgeoisie » et jura de ne pas « répéter cette erreur ». Il s'est donc bien « formé » idéologiquement, au moins en partie, à travers l'histoire et les leçons qu'on tirait alors de la Commune"},
+        {role: "user", content: "cette information ne m'interesse pas"},
+      ],
+        userId,
+        {},
+      )) as SearchResult;
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBe(0);
+
+    });
+
+    it("should remember encoded user preferences", async () => {
+      // First add a memory
+      const addResult = (await memory.capture(
+        "lorsque j'utilise la commande spéciale 'en\"\"' dans mes questions tu dois traduire le texte",
+        userId,
+        {},
+      )) as SearchResult;
+
+      if (!addResult.results?.[0]?.id) {
+        throw new Error("Failed to create test memory");
+      }
+
+
+      const result = (await memory.retrieve(
+        "en\"\"quelle est l'âge du capitaine\"\"",
+        userId,
+        {},
+      )) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      expect(result.results.length).toBeGreaterThan(0);
+    });
+
+
+
+    it("should include 'type' field when capturing and retrieving memory", async () => {
+      const captureResult = await memory.capture(
+        "User likes sushi.",
+        userId,
+        {},
+      );
+
+      expect(captureResult.results).toBeDefined();
+      expect(captureResult.results.length).toBeGreaterThan(0);
+      const memoryId = captureResult.results[0]?.id;
+      expect(memoryId).toBeDefined();
+      
+      // Verify the type is present in the capture result (returned immediately)
+      // Note: The LLM decides the type, so we check for its existence, not a specific value unless mocked.
+      expect(captureResult.results[0]?.type).toBeDefined();
+      expect(typeof captureResult.results[0]?.type).toBe('string');
+
+      // Retrieve the memory to check persistence
+      const retrievedMemory = await memory.get(memoryId!, userId);
+      expect(retrievedMemory).not.toBeNull();
+      expect(retrievedMemory?.type).toBeDefined();
+      expect(typeof retrievedMemory?.type).toBe('string');
+      // Check payload directly via retrieve (which gets it from vector store)
+       const searchResult = await memory.retrieve("User preference on food", userId, {});
+       expect(searchResult.results).toBeDefined();
+       expect(searchResult.results.length).toBeGreaterThan(0);
+       const foundMemory = searchResult.results.find(m => m.id === memoryId);
+       expect(foundMemory).toBeDefined();
+       expect(foundMemory?.type).toBeDefined();
+       expect(typeof foundMemory?.type).toBe('string');
+    });
+
+    it("should ensure 'type' field is passed to vector store during capture (ADD)", async () => {
+      const mockVectorStore = {
+        insert: jest.fn().mockResolvedValue(undefined),
+        search: jest.fn().mockResolvedValue([]), // Mock search to avoid errors in update logic
+        get: jest.fn(),
+        list: jest.fn(),
+        update: jest.fn(),
+        delete: jest.fn(),
+        deleteCol: jest.fn(),
+        ensureCollection: jest.fn(),
+      };
+      
+      // Mock the getVectorStore method to return our mock
+      jest.spyOn(memory, 'getVectorStore').mockResolvedValue(mockVectorStore as any);
+
+      // Mock LLM responses to force an ADD action with a specific type
+      const mockLlm = {
+        generateResponse: jest.fn()
+          .mockResolvedValueOnce({ // Fact extraction response
+            facts: [{ fact: "User likes cats", type: "PREFERENCE" }] 
+          })
+          .mockResolvedValueOnce({ // Memory update response
+            memory: [{ event: "ADD", text: "User likes cats", type: "PREFERENCE" }] 
+          })
+      };
+       // Replace the LLM instance with the mock
+      (memory as any).llm = mockLlm;
+
+
+      await memory.capture("User likes cats", userId, {});
+
+      // Verify mockVectorStore.insert was called
+      expect(mockVectorStore.insert).toHaveBeenCalled();
+
+      // Get the arguments passed to the insert call
+      const insertArgs = mockVectorStore.insert.mock.calls[0];
+      const metadataPayload = insertArgs[2][0]; // Metadata is the third argument, first item in the array
+
+      // Assert that the type field is present in the metadata payload
+      expect(metadataPayload).toBeDefined();
+      expect(metadataPayload.type).toBe('PREFERENCE'); 
+    });
+
+  });
+
+  describe("Memory with Custom Configuration", () => {
+    let customMemory: MemoriesLite;
+
+    beforeEach(() => {
+      customMemory = new MemoriesLite({
+        version: "v1.1",
+        disableHistory: true,
+        embedder: {
+          provider: "openai",
+          config: {
+            dimension,
+            apiKey: process.env.OPENAI_API_KEY || "",
+            model: "text-embedding-3-small",
+          },
+        },
+        vectorStore: {
+          provider: "lite",
+          config: {
+            dimension,
+            rootPath: ":memory:",
+          },
+        },
+        llm: {
+          provider: "openai",
+          config: {
+            apiKey: process.env.OPENAI_API_KEY || "",
+            model: "gpt-4.1-mini",
+          },
+        },
+        historyDbPath: ":memory:", // Use in-memory SQLite for tests
+      });
+    });
+
+    afterEach(async () => {
+      await customMemory.reset(userId);
+    });
+
+
+    it("should perform semantic search with custom embeddings", async () => {
+      // Add test memories
+      await customMemory.capture("The weather in London is rainy today", userId, {});
+      await customMemory.capture("The temperature in Paris is 25 degrees", userId, {});
+
+      const result = (await customMemory.retrieve(
+        "What is the weather like?",
+        userId,
+        {},
+      )) as SearchResult;
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.results)).toBe(true);
+      // Results should be ordered by relevance
+      expect(result.results.length).toBe(0);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*", "jest.config.js"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/config/defaults.ts","./src/config/manager.ts","./src/embeddings/base.ts","./src/embeddings/google.ts","./src/embeddings/openai.ts","./src/graphs/configs.ts","./src/graphs/tools.ts","./src/graphs/utils.ts","./src/llms/base.ts","./src/llms/google.ts","./src/llms/openai.ts","./src/llms/openai_structured.ts","./src/memory/index.ts","./src/memory/memory.types.ts","./src/prompts/index.ts","./src/storage/DummyHistoryManager.ts","./src/storage/MemoryHistoryManager.ts","./src/storage/base.ts","./src/storage/index.ts","./src/types/index.ts","./src/utils/bm25.ts","./src/utils/factory.ts","./src/utils/logger.ts","./src/utils/memory.ts","./src/utils/telemetry.ts","./src/utils/telemetry.types.ts","./src/vectorstores/base.ts","./src/vectorstores/lite.ts","./src/vectorstores/llm.ts"],"version":"5.8.3"}