aimemory-core 1.0.1

package/tests/contextBuilder.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryManager } from '../src/memoryManager.js';
+import { ContextBuilder } from '../src/contextBuilder.js';
+import { EmbeddingFunction } from '../src/types.js';
+
+const mockEmbedding: EmbeddingFunction = async (text: string): Promise<number[]> => {
+  const hash = text.split('').reduce((acc, char) => {
+    return ((acc << 5) - acc) + char.charCodeAt(0);
+  }, 0);
+  
+  const embedding = new Array(1536).fill(0);
+  for (let i = 0; i < embedding.length; i++) {
+    embedding[i] = Math.sin(hash * i) * Math.cos(hash * i);
+  }
+  
+  const magnitude = Math.sqrt(embedding.reduce((sum, val) => sum + val * val, 0));
+  return embedding.map(val => val / magnitude);
+};
+
+describe('ContextBuilder', () => {
+  let manager: MemoryManager;
+  let builder: ContextBuilder;
+
+  beforeEach(async () => {
+    manager = new MemoryManager();
+    manager.setEmbeddingFunction(mockEmbedding);
+
+    await manager.addFact('The user prefers dark mode');
+    await manager.addFact('User lives in New York');
+    await manager.addPreference('User likes bullet point summaries');
+    await manager.addPreference('User prefers concise responses');
+    await manager.addInstruction('Always verify information');
+    await manager.addConversation('Hello, how are you?', 'user', { sessionId: 'test' });
+    await manager.addConversation('I am doing great!', 'assistant', { sessionId: 'test' });
+
+    builder = new ContextBuilder(manager, {
+      maxTokens: 2000,
+      relevanceThreshold: 0.1,
+      maxMemories: 10,
+    });
+  });
+
+  it('should build context with system prompt', async () => {
+    const result = await builder.buildContext('user preferences');
+
+    expect(result.messages.length).toBeGreaterThan(0);
+    expect(result.messages[0].role).toBe('system');
+  });
+
+  it('should exclude system prompt when configured', async () => {
+    builder.updateConfig({ includeSystemPrompt: false });
+    
+    const result = await builder.buildContext('test query');
+
+    const hasSystemPrompt = result.messages.some(m => m.role === 'system');
+    expect(hasSystemPrompt).toBe(false);
+  });
+
+  it('should include relevant memories in context', async () => {
+    const result = await builder.buildContext('test');
+
+    expect(result.messages.length).toBeGreaterThan(0);
+  });
+
+  it('should estimate tokens correctly', async () => {
+    const result = await builder.buildContext('test');
+
+    expect(result.stats.tokensEstimated).toBeGreaterThan(0);
+  });
+
+  it('should respect maxMemories config', async () => {
+    builder.updateConfig({ maxMemories: 2 });
+    
+    const result = await builder.buildContext('test query');
+
+    expect(result.stats.memoriesUsed).toBeLessThanOrEqual(2);
+  });
+
+  it('should respect relevance threshold', async () => {
+    builder.updateConfig({ relevanceThreshold: 0.9 });
+    
+    const result = await builder.buildContext('test');
+
+    expect(result.stats.memoriesUsed).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should include metadata when configured', async () => {
+    builder.updateConfig({ includeMetadata: true });
+    
+    const result = await builder.buildContext('test');
+
+    expect(result.messages.length).toBeGreaterThan(0);
+  });
+
+  it('should group memories by type in context', async () => {
+    const result = await builder.buildContext('test');
+
+    expect(result.messages.length).toBeGreaterThan(0);
+  });
+
+  it('should handle empty results', async () => {
+    const emptyManager = new MemoryManager();
+    emptyManager.setEmbeddingFunction(mockEmbedding);
+    const emptyBuilder = new ContextBuilder(emptyManager);
+
+    const result = await emptyBuilder.buildContext('nonexistent query');
+
+    expect(result.messages.length).toBeGreaterThan(0);
+  });
+
+  it('should return stats object', async () => {
+    const result = await builder.buildContext('test');
+
+    expect(result.stats).toHaveProperty('memoriesUsed');
+    expect(result.stats).toHaveProperty('tokensEstimated');
+    expect(result.stats).toHaveProperty('truncationApplied');
+  });
+
+  it('should track truncation', async () => {
+    builder.updateConfig({ maxTokens: 10 });
+    
+    const result = await builder.buildContext('test');
+
+    expect(typeof result.stats.truncationApplied).toBe('boolean');
+  });
+
+  it('should allow custom system prompt', async () => {
+    builder.updateConfig({ 
+      includeSystemPrompt: true,
+      systemPrompt: 'Custom system prompt',
+    });
+    
+    const result = await builder.buildContext('test');
+
+    const systemMsg = result.messages.find(m => m.role === 'system');
+    expect(systemMsg?.content).toContain('Custom system prompt');
+  });
+});

package/tests/memoryManager.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryManager } from '../src/memoryManager.js';
+import { EmbeddingFunction } from '../src/types.js';
+
+const mockEmbedding: EmbeddingFunction = async (text: string): Promise<number[]> => {
+  const hash = text.split('').reduce((acc, char) => {
+    return ((acc << 5) - acc) + char.charCodeAt(0);
+  }, 0);
+  
+  const embedding = new Array(1536).fill(0);
+  for (let i = 0; i < embedding.length; i++) {
+    embedding[i] = Math.sin(hash * i) * Math.cos(hash * i);
+  }
+  
+  const magnitude = Math.sqrt(embedding.reduce((sum, val) => sum + val * val, 0));
+  return embedding.map(val => val / magnitude);
+};
+
+describe('MemoryManager', () => {
+  let manager: MemoryManager;
+
+  beforeEach(() => {
+    manager = new MemoryManager();
+    manager.setEmbeddingFunction(mockEmbedding);
+  });
+
+  it('should add memory', async () => {
+    const memory = await manager.addMemory('Test content', {
+      type: 'fact',
+      importance: 0.8,
+    });
+
+    expect(memory.content).toBe('Test content');
+    expect(memory.metadata.type).toBe('fact');
+    expect(memory.metadata.importance).toBe(0.8);
+    expect(memory.id).toBeDefined();
+  });
+
+  it('should add conversation', async () => {
+    const memory = await manager.addConversation('Hello', 'user', {
+      sessionId: 'session-1',
+    });
+
+    expect(memory.content).toBe('User: Hello');
+    expect(memory.metadata.type).toBe('conversation');
+    expect(memory.metadata.sessionId).toBe('session-1');
+  });
+
+  it('should add fact with high importance', async () => {
+    const memory = await manager.addFact('The sky is blue');
+
+    expect(memory.metadata.type).toBe('fact');
+    expect(memory.metadata.importance).toBeGreaterThanOrEqual(0.7);
+  });
+
+  it('should add preference with default importance', async () => {
+    const memory = await manager.addPreference('I prefer dark mode');
+
+    expect(memory.metadata.type).toBe('preference');
+    expect(memory.metadata.importance).toBeGreaterThanOrEqual(0.6);
+  });
+
+  it('should add instruction with high importance', async () => {
+    const memory = await manager.addInstruction('Always verify facts');
+
+    expect(memory.metadata.type).toBe('instruction');
+    expect(memory.metadata.importance).toBeGreaterThanOrEqual(0.9);
+  });
+
+  it('should search memories', async () => {
+    await manager.addMemory('Python is a programming language', { type: 'fact' });
+    await manager.addMemory('JavaScript is also a programming language', { type: 'fact' });
+    await manager.addMemory('The weather is nice today', { type: 'context' });
+
+    const results = await manager.search({
+      text: 'programming language',
+      limit: 5,
+    });
+
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  it('should get memory by id', async () => {
+    const added = await manager.addMemory('Test content');
+    
+    const retrieved = await manager.getMemory(added.id);
+    
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.content).toBe('Test content');
+  });
+
+  it('should return null for non-existent id', async () => {
+    const retrieved = await manager.getMemory('non-existent-id');
+    expect(retrieved).toBeNull();
+  });
+
+  it('should update memory', async () => {
+    const added = await manager.addMemory('Original content');
+    
+    const updated = await manager.updateMemory(added.id, {
+      content: 'Updated content',
+    });
+
+    expect(updated).not.toBeNull();
+    expect(updated!.content).toBe('Updated content');
+  });
+
+  it('should delete memory', async () => {
+    const added = await manager.addMemory('To be deleted');
+    
+    await manager.deleteMemory(added.id);
+    
+    const retrieved = await manager.getMemory(added.id);
+    expect(retrieved).toBeNull();
+  });
+
+  it('should get recent memories', async () => {
+    await manager.addMemory('First');
+    await manager.addMemory('Second');
+    await manager.addMemory('Third');
+
+    const recent = await manager.getRecentMemories(2);
+    
+    expect(recent).toHaveLength(2);
+  });
+
+  it('should get memories by type', async () => {
+    await manager.addMemory('A fact', { type: 'fact' });
+    await manager.addMemory('Another fact', { type: 'fact' });
+    await manager.addMemory('A preference', { type: 'preference' });
+
+    const facts = await manager.getMemoriesByType('fact');
+    
+    expect(facts).toHaveLength(2);
+  });
+
+  it('should get memories by tag', async () => {
+    await manager.addMemory('Memory 1', { tags: ['important', 'work'] });
+    await manager.addMemory('Memory 2', { tags: ['important'] });
+    await manager.addMemory('Memory 3', { tags: ['personal'] });
+
+    const important = await manager.getMemoriesByTag('important');
+    
+    expect(important).toHaveLength(2);
+  });
+
+  it('should get memories by user', async () => {
+    await manager.addMemory('User A memory', { userId: 'user-a' });
+    await manager.addMemory('User A another', { userId: 'user-a' });
+    await manager.addMemory('User B memory', { userId: 'user-b' });
+
+    const userAMemories = await manager.getMemoriesByUser('user-a');
+    
+    expect(userAMemories).toHaveLength(2);
+  });
+
+  it('should get stats', async () => {
+    await manager.addMemory('Fact 1', { type: 'fact' });
+    await manager.addMemory('Fact 2', { type: 'fact' });
+    await manager.addMemory('Preference 1', { type: 'preference' });
+
+    const stats = await manager.getStats();
+    
+    expect(stats.totalMemories).toBe(3);
+    expect(stats.memoriesByType.fact).toBe(2);
+    expect(stats.memoriesByType.preference).toBe(1);
+  });
+
+  it('should export and import data', async () => {
+    await manager.addMemory('Memory 1', { type: 'fact' });
+    await manager.addMemory('Memory 2', { type: 'preference' });
+
+    const exported = await manager.exportData();
+    
+    const newManager = new MemoryManager();
+    await newManager.importData(exported);
+
+    const stats = await newManager.getStats();
+    expect(stats.totalMemories).toBe(2);
+  });
+
+  it('should clear all memories', async () => {
+    await manager.addMemory('Memory 1');
+    await manager.addMemory('Memory 2');
+
+    await manager.clear();
+
+    const stats = await manager.getStats();
+    expect(stats.totalMemories).toBe(0);
+  });
+
+  it('should respect maxMemories config', async () => {
+    const limitedManager = new MemoryManager({ maxMemories: 3 });
+    limitedManager.setEmbeddingFunction(mockEmbedding);
+
+    await limitedManager.addMemory('Memory 1');
+    await limitedManager.addMemory('Memory 2');
+    await limitedManager.addMemory('Memory 3');
+    await limitedManager.addMemory('Memory 4');
+    await limitedManager.addMemory('Memory 5');
+
+    const stats = await limitedManager.getStats();
+    expect(stats.totalMemories).toBeLessThanOrEqual(5);
+  });
+});

package/tests/metadataStore.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MetadataStore } from '../src/metadataStore.js';
+import { Memory, MemoryType } from '../src/types.js';
+
+describe('MetadataStore', () => {
+  let store: MetadataStore;
+
+  const createMemory = (overrides: Partial<Memory> = {}): Memory => ({
+    id: `mem-${Math.random().toString(36).substr(2, 9)}`,
+    content: 'Test memory content',
+    timestamp: Date.now(),
+    metadata: {
+      type: 'context' as MemoryType,
+      importance: 0.5,
+      tags: [],
+      ...overrides.metadata,
+    },
+    ...overrides,
+  });
+
+  beforeEach(() => {
+    store = new MetadataStore();
+  });
+
+  it('should add memories', async () => {
+    const memory = createMemory();
+    await store.add(memory);
+
+    const retrieved = await store.getById(memory.id);
+    expect(retrieved).not.toBeNull();
+    expect(retrieved!.content).toBe(memory.content);
+  });
+
+  it('should update existing memories', async () => {
+    const memory = createMemory();
+    await store.add(memory);
+
+    await store.update({ ...memory, content: 'Updated content' });
+
+    const retrieved = await store.getById(memory.id);
+    expect(retrieved!.content).toBe('Updated content');
+  });
+
+  it('should delete memories', async () => {
+    const memory = createMemory();
+    await store.add(memory);
+
+    await store.delete(memory.id);
+
+    const retrieved = await store.getById(memory.id);
+    expect(retrieved).toBeNull();
+  });
+
+  it('should index by type', async () => {
+    await store.add(createMemory({ metadata: { type: 'fact' } }));
+    await store.add(createMemory({ metadata: { type: 'fact' } }));
+    await store.add(createMemory({ metadata: { type: 'preference' } }));
+
+    const facts = await store.find({ types: ['fact'] }, 10);
+    expect(facts).toHaveLength(2);
+  });
+
+  it('should index by tags', async () => {
+    await store.add(createMemory({ metadata: { tags: ['tag1', 'tag2'] } }));
+    await store.add(createMemory({ metadata: { tags: ['tag1'] } }));
+    await store.add(createMemory({ metadata: { tags: ['tag3'] } }));
+
+    const results = await store.find({ tags: ['tag1'] }, 10);
+    expect(results).toHaveLength(2);
+  });
+
+  it('should filter by userId', async () => {
+    await store.add(createMemory({ metadata: { userId: 'user-1' } }));
+    await store.add(createMemory({ metadata: { userId: 'user-1' } }));
+    await store.add(createMemory({ metadata: { userId: 'user-2' } }));
+
+    const results = await store.find({ userId: 'user-1' }, 10);
+    expect(results).toHaveLength(2);
+  });
+
+  it('should filter by importance range', async () => {
+    await store.add(createMemory({ metadata: { importance: 0.3 } }));
+    await store.add(createMemory({ metadata: { importance: 0.7 } }));
+    await store.add(createMemory({ metadata: { importance: 0.5 } }));
+
+    const results = await store.find({ minImportance: 0.4, maxImportance: 0.8 }, 10);
+    expect(results).toHaveLength(2);
+  });
+
+  it('should get recent memories', async () => {
+    const now = Date.now();
+    await store.add(createMemory({ timestamp: now - 1000 }));
+    await store.add(createMemory({ timestamp: now }));
+    await store.add(createMemory({ timestamp: now + 1000 }));
+
+    const recent = await store.getRecent(2);
+    expect(recent).toHaveLength(2);
+  });
+
+  it('should get statistics', async () => {
+    await store.add(createMemory({ metadata: { type: 'fact' } }));
+    await store.add(createMemory({ metadata: { type: 'fact' } }));
+    await store.add(createMemory({ metadata: { type: 'preference', tags: ['test'] } }));
+
+    const stats = await store.getStats();
+    
+    expect(stats.totalMemories).toBe(3);
+    expect(stats.memoriesByType.fact).toBe(2);
+    expect(stats.memoriesByType.preference).toBe(1);
+    expect(stats.memoriesByTag['test']).toBe(1);
+  });
+
+  it('should clear all memories', async () => {
+    await store.add(createMemory());
+    await store.add(createMemory());
+
+    await store.clear();
+
+    const size = await store.size();
+    expect(size).toBe(0);
+  });
+
+  it('should return correct size', async () => {
+    await store.add(createMemory());
+    await store.add(createMemory());
+    await store.add(createMemory());
+
+    const size = await store.size();
+    expect(size).toBe(3);
+  });
+});

package/tests/rateLimiter.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { RateLimiter, InMemoryRateLimitStore } from '../src/rateLimiter';
+
+describe('RateLimiter', () => {
+  let limiter: RateLimiter;
+
+  beforeEach(() => {
+    const store = new InMemoryRateLimitStore();
+    limiter = new RateLimiter({ windowMs: 60000, maxRequests: 5 }, store);
+  });
+
+  it('should allow requests within limit', async () => {
+    const result = await limiter.check('user1');
+    expect(result.allowed).toBe(true);
+    expect(result.remaining).toBe(4);
+  });
+
+  it('should track remaining requests', async () => {
+    await limiter.check('user1');
+    await limiter.check('user1');
+    
+    const result = await limiter.check('user1');
+    expect(result.remaining).toBe(2);
+  });
+
+  it('should block when limit reached', async () => {
+    for (let i = 0; i < 5; i++) {
+      await limiter.check('user1');
+    }
+    
+    const result = await limiter.check('user1');
+    expect(result.allowed).toBe(false);
+    expect(result.remaining).toBe(0);
+  });
+
+  it('should track different users separately', async () => {
+    await limiter.check('user1');
+    await limiter.check('user1');
+    
+    const result1 = await limiter.check('user1');
+    const result2 = await limiter.check('user2');
+    
+    expect(result1.remaining).toBe(2);
+    expect(result2.remaining).toBe(4);
+  });
+
+  it('should reset user limit', async () => {
+    for (let i = 0; i < 5; i++) {
+      await limiter.check('user1');
+    }
+    
+    await limiter.reset('user1');
+    
+    const result = await limiter.check('user1');
+    expect(result.allowed).toBe(true);
+  });
+});

package/tests/usageTracker.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { UsageTracker, InMemoryUsageStore, DEFAULT_USAGE_LIMITS } from '../src/usageTracker';
+
+describe('UsageTracker', () => {
+  let tracker: UsageTracker;
+
+  beforeEach(() => {
+    const store = new InMemoryUsageStore();
+    tracker = new UsageTracker(DEFAULT_USAGE_LIMITS.free, store);
+  });
+
+  it('should track memories added', async () => {
+    await tracker.recordUsage('user1', 'memories_added');
+    
+    const result = await tracker.checkLimit('user1', 'memories_added');
+    expect(result.current).toBe(1);
+    expect(result.remaining).toBe(999);
+  });
+
+  it('should track api calls', async () => {
+    await tracker.recordUsage('user1', 'api_calls');
+    await tracker.recordUsage('user1', 'api_calls');
+    await tracker.recordUsage('user1', 'api_calls');
+    
+    const result = await tracker.checkLimit('user1', 'api_calls');
+    expect(result.current).toBe(3);
+    expect(result.remaining).toBe(997);
+  });
+
+  it('should block when limit reached', async () => {
+    const limits = { ...DEFAULT_USAGE_LIMITS.free, maxApiCallsPerDay: 2 };
+    const limitedTracker = new UsageTracker(limits);
+    
+    await limitedTracker.recordUsage('user1', 'api_calls');
+    await limitedTracker.recordUsage('user1', 'api_calls');
+    
+    const result = await limitedTracker.checkLimit('user1', 'api_calls');
+    expect(result.allowed).toBe(false);
+  });
+
+  it('should get usage summary', async () => {
+    await tracker.recordUsage('user1', 'memories_added');
+    await tracker.recordUsage('user1', 'api_calls');
+    await tracker.recordUsage('user1', 'api_calls');
+    
+    const summary = await tracker.getUsageSummary('user1', 'daily');
+    expect(summary.totalOperations).toBe(3);
+    expect(summary.metrics.memories_added).toBe(1);
+    expect(summary.metrics.api_calls).toBe(2);
+  });
+
+  it('should track different users separately', async () => {
+    await tracker.recordUsage('user1', 'api_calls');
+    await tracker.recordUsage('user2', 'api_calls');
+    
+    const result1 = await tracker.checkLimit('user1', 'api_calls');
+    const result2 = await tracker.checkLimit('user2', 'api_calls');
+    
+    expect(result1.current).toBe(1);
+    expect(result2.current).toBe(1);
+  });
+});

package/tests/vectorStore.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InMemoryVectorStore } from '../src/vectorStore.js';
+
+describe('InMemoryVectorStore', () => {
+  let store: InMemoryVectorStore;
+
+  beforeEach(() => {
+    store = new InMemoryVectorStore(3);
+  });
+
+  it('should add vectors', async () => {
+    await store.add([
+      { id: '1', vector: [1, 0, 0], metadata: { text: 'test1' } },
+      { id: '2', vector: [0, 1, 0], metadata: { text: 'test2' } },
+    ]);
+
+    const size = await store.size();
+    expect(size).toBe(2);
+  });
+
+  it('should throw on invalid dimension', async () => {
+    await expect(
+      store.add([{ id: '1', vector: [1, 2], metadata: {} }])
+    ).rejects.toThrow('Invalid vector dimension');
+  });
+
+  it('should search by cosine similarity', async () => {
+    await store.add([
+      { id: '1', vector: [1, 0, 0], metadata: { text: 'similar' } },
+      { id: '2', vector: [0, 1, 0], metadata: { text: 'different' } },
+    ]);
+
+    const results = await store.search([1, 0, 0], { limit: 2 });
+    
+    expect(results).toHaveLength(2);
+    expect(results[0].memory.metadata.text).toBe('similar');
+    expect(results[0].score).toBeGreaterThan(results[1].score);
+  });
+
+  it('should filter by threshold', async () => {
+    await store.add([
+      { id: '1', vector: [1, 0, 0], metadata: { text: 'high' } },
+      { id: '2', vector: [0.1, 0.1, 0.1], metadata: { text: 'low' } },
+    ]);
+
+    const results = await store.search([1, 0, 0], { limit: 2, threshold: 0.9 });
+    
+    expect(results).toHaveLength(1);
+    expect(results[0].memory.metadata.text).toBe('high');
+  });
+
+  it('should delete vectors', async () => {
+    await store.add([
+      { id: '1', vector: [1, 0, 0], metadata: {} },
+    ]);
+
+    await store.delete(['1']);
+    
+    const size = await store.size();
+    expect(size).toBe(0);
+  });
+
+  it('should get by id', async () => {
+    await store.add([
+      { id: 'test-id', vector: [1, 2, 3], metadata: { data: 'value' } },
+    ]);
+
+    const entry = await store.getById('test-id');
+    
+    expect(entry).not.toBeNull();
+    expect(entry!.metadata.data).toBe('value');
+  });
+
+  it('should return null for non-existent id', async () => {
+    const entry = await store.getById('non-existent');
+    expect(entry).toBeNull();
+  });
+
+  it('should clear all vectors', async () => {
+    await store.add([
+      { id: '1', vector: [1, 0, 0], metadata: {} },
+      { id: '2', vector: [0, 1, 0], metadata: {} },
+    ]);
+
+    await store.clear();
+    
+    const size = await store.size();
+    expect(size).toBe(0);
+  });
+
+  it('should calculate cosine similarity correctly', async () => {
+    await store.add([
+      { id: '1', vector: [1, 0, 0], metadata: { content: 'a' } },
+      { id: '2', vector: [0, 1, 0], metadata: { content: 'b' } },
+      { id: '3', vector: [1, 1, 0], metadata: { content: 'c' } },
+    ]);
+
+    const results = await store.search([1, 0, 0], { limit: 3 });
+    
+    expect(results[0].score).toBe(1);
+    const scores = results.map(r => r.score);
+    expect(scores).toContain(0);
+    const hasMiddleScore = scores.some(s => s > 0.5 && s < 1);
+    expect(hasMiddleScore).toBe(true);
+  });
+});