aimemory-core 1.0.1

package/examples/advanced.ts

@@ -0,0 +1,164 @@
+import { createAIMemory, createMemoryManager, createContextBuilder, EmbeddingFunction, MemoryType } from '../src/index.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);
+};
+
+async function advancedExample() {
+  console.log('=== AI Memory Advanced Example ===\n');
+
+  const memory = createAIMemory({
+    maxMemories: 5000,
+    embeddingDimension: 1536,
+    context: {
+      maxTokens: 4000,
+      relevanceThreshold: 0.5,
+      memoryTypes: ['fact', 'preference', 'instruction', 'conversation', 'context'],
+      maxMemories: 15,
+    },
+    autoCleanup: {
+      enabled: true,
+      maxAge: 90 * 24 * 60 * 60 * 1000,
+      minImportance: 0.3,
+    },
+  });
+
+  memory.setEmbeddingFunction(mockEmbedding);
+
+  console.log('--- Multi-user Scenario ---\n');
+
+  console.log('1. Adding memories for User A...');
+  await memory.rememberFact('User A lives in Buenos Aires, Argentina', {
+    userId: 'user-a',
+    tags: ['location', 'personal'],
+  });
+  
+  await memory.rememberFact('User A is a data scientist', {
+    userId: 'user-a',
+    tags: ['profession', 'work'],
+  });
+
+  await memory.rememberPreference('User A prefers Python over JavaScript', {
+    userId: 'user-a',
+    tags: ['programming', 'preferences'],
+  });
+
+  console.log('2. Adding memories for User B...');
+  await memory.rememberFact('User B lives in Madrid, Spain', {
+    userId: 'user-b',
+    tags: ['location', 'personal'],
+  });
+
+  await memory.rememberFact('User B is a UX designer', {
+    userId: 'user-b',
+    tags: ['profession', 'work'],
+  });
+
+  await memory.rememberPreference('User B prefers Figma for design work', {
+    userId: 'user-b',
+    tags: ['tools', 'preferences'],
+  });
+
+  console.log('\n--- Session Management ---\n');
+
+  console.log('3. Creating conversation session...');
+  const sessionId = 'session-conversation-001';
+  
+  await memory.rememberConversation('Can you help me with Python数据分析?', 'user', {
+    userId: 'user-a',
+    sessionId,
+    tags: ['question', 'python'],
+  });
+
+  await memory.rememberConversation('Of course! I can help you with data analysis in Python. What specific task would you like to accomplish?', 'assistant', {
+    userId: 'user-a',
+    sessionId,
+    tags: ['response', 'help'],
+  });
+
+  console.log('4. Retrieving session memories...');
+  const memoryManager = memory.getMemoryManager();
+  const sessionMemories = await memoryManager.getMemoriesBySession(sessionId);
+  console.log(`Found ${sessionMemories.length} memories in session ${sessionId}`);
+
+  console.log('\n--- Context Building ---\n');
+
+  console.log('5. Building context for User A...');
+  const contextA = await memory.getContext('programming preferences');
+  console.log(`Context includes ${contextA.stats.memoriesUsed} memories`);
+  
+  for (const msg of contextA.messages) {
+    if (msg.role === 'system' && msg.content.includes('User Preferences')) {
+      console.log('User preferences found in context');
+    }
+  }
+
+  console.log('\n6. Searching with filters...');
+  const facts = await memoryManager.getMemoriesByType('fact' as MemoryType);
+  console.log(`Total facts: ${facts.length}`);
+
+  const userAPreferences = await memoryManager.getMemoriesByUser('user-a');
+  console.log(`User A memories: ${userAPreferences.length}`);
+
+  console.log('\n7. Updating a memory...');
+  const searchResults = await memory.recall('Python preference');
+  if (searchResults.length > 0) {
+    const memoryToUpdate = searchResults[0].memory;
+    await memory.updateMemory(memoryToUpdate.id, {
+      content: 'User A prefers Python over JavaScript and uses it for data science projects',
+    });
+    console.log('Memory updated successfully');
+  }
+
+  console.log('\n8. Getting comprehensive stats...');
+  const stats = await memory.getStats();
+  console.log(`
+    Total memories: ${stats.totalMemories}
+    By type:
+      - Facts: ${stats.memoriesByType.fact}
+      - Preferences: ${stats.memoriesByType.preference}
+      - Conversations: ${stats.memoriesByType.conversation}
+    By tag:
+      - user-a: ${stats.memoriesByTag['user-a'] || 0}
+      - user-b: ${stats.memoriesByTag['user-b'] || 0}
+  `);
+
+  console.log('\n9. Using MemoryManager directly...');
+  const manager = createMemoryManager();
+  manager.setEmbeddingFunction(mockEmbedding);
+
+  await manager.addMemory('Direct memory added', {
+    type: 'context',
+    importance: 0.8,
+    tags: ['direct', 'test'],
+  });
+
+  const directSearch = await manager.search({
+    text: 'Direct memory added',
+    limit: 5,
+  });
+  console.log(`Found ${directSearch.length} direct memories`);
+
+  console.log('\n10. Using ContextBuilder directly...');
+  const contextBuilder = createContextBuilder(manager, {
+    maxTokens: 1000,
+    includeMetadata: true,
+  });
+
+  const directContext = await contextBuilder.buildContext('test query');
+  console.log(`Built context with ${directContext.messages.length} messages`);
+
+  console.log('\n=== Advanced example completed! ===');
+}
+
+advancedExample().catch(console.error);

package/examples/basic.ts

@@ -0,0 +1,87 @@
+import { createAIMemory, EmbeddingFunction } from '../src/index.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);
+};
+
+async function main() {
+  const memory = createAIMemory({
+    maxMemories: 1000,
+    context: {
+      maxTokens: 2000,
+      relevanceThreshold: 0.6,
+    },
+  });
+
+  memory.setEmbeddingFunction(mockEmbedding);
+
+  console.log('=== AI Memory Basic Example ===\n');
+
+  console.log('1. Remembering facts...');
+  await memory.rememberFact('The user prefers dark mode interface', {
+    userId: 'user-123',
+    tags: ['preferences', 'ui'],
+  });
+  
+  await memory.rememberFact('User works as a software developer', {
+    userId: 'user-123',
+    tags: ['work', 'developer'],
+  });
+
+  console.log('2. Remembering preferences...');
+  await memory.rememberPreference('I like to receive summaries in bullet points', {
+    userId: 'user-123',
+    tags: ['communication', 'format'],
+  });
+
+  console.log('3. Remembering conversation...');
+  await memory.rememberConversation('Hello! How are you?', 'user', {
+    userId: 'user-123',
+    sessionId: 'session-1',
+  });
+  
+  await memory.rememberConversation('Hello! I am doing great, thank you for asking!', 'assistant', {
+    userId: 'user-123',
+    sessionId: 'session-1',
+  });
+
+  console.log('4. Remembering instructions...');
+  await memory.rememberInstruction('Always verify information before responding', {
+    userId: 'user-123',
+    importance: 0.9,
+  });
+
+  console.log('\n5. Recalling relevant memories...');
+  const results = await memory.recall('user preferences interface');
+  console.log(`Found ${results.length} relevant memories:`);
+  for (const result of results) {
+    console.log(`  - [${result.memory.metadata.type}] (score: ${result.score.toFixed(2)}) ${result.memory.content}`);
+  }
+
+  console.log('\n6. Building context for LLM...');
+  const context = await memory.getContext('What does the user prefer?');
+  console.log('Context messages:');
+  for (const msg of context.messages) {
+    console.log(`  [${msg.role}]: ${msg.content.substring(0, 100)}...`);
+  }
+  console.log(`\nStats: Memories used: ${context.stats.memoriesUsed}, Tokens estimated: ${context.stats.tokensEstimated}`);
+
+  console.log('\n7. Getting statistics...');
+  const stats = await memory.getStats();
+  console.log(`Total memories: ${stats.totalMemories}`);
+  console.log('Memories by type:', stats.memoriesByType);
+
+  console.log('\n=== Example completed successfully! ===');
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "aimemory-core",
+  "version": "1.0.1",
+  "description": "Persistent memory system for LLM applications - semantic search, context management, and monetization ready",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "docs": "typedoc"
+  },
+  "keywords": [
+    "ai",
+    "memory",
+    "llm",
+    "context",
+    "persistent",
+    "semantic-search",
+    "vector-store",
+    "embedding",
+    "rate-limit",
+    "usage-tracking",
+    "monetization",
+    "saas"
+  ],
+  "author": "Gabriel Pitrella <support@aimemory.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gpitrella/ai-memory"
+  },
+  "bugs": {
+    "url": "https://github.com/gpitrella/ai-memory/issues"
+  },
+  "homepage": "https://aimemory.dev",
+  "dependencies": {
+    "ioredis": "^5.10.1",
+    "pg": "^8.20.0",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/pg": "^8.20.0",
+    "@types/uuid": "^9.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.55.0",
+    "prettier": "^3.1.0",
+    "typedoc": "^0.25.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,65 @@
+import { ContextConfig, MemoryType } from './types.js';
+
+export interface AIMemoryConfig {
+  storagePath: string;
+  maxMemories: number;
+  defaultImportance: number;
+  embeddingDimension: number;
+  context: ContextConfig;
+  autoCleanup: {
+    enabled: boolean;
+    maxAge: number;
+    minImportance: number;
+  };
+  logging: {
+    enabled: boolean;
+    level: 'debug' | 'info' | 'warn' | 'error';
+  };
+}
+
+export const DEFAULT_CONFIG: AIMemoryConfig = {
+  storagePath: './ai-memory-data',
+  maxMemories: 10000,
+  defaultImportance: 0.5,
+  embeddingDimension: 1536,
+  context: {
+    maxTokens: 4000,
+    includeSystemPrompt: true,
+    systemPrompt: 'You are a helpful AI assistant with memory of past conversations.',
+    relevanceThreshold: 0.7,
+    includeMetadata: false,
+    memoryTypes: ['conversation', 'fact', 'preference', 'context'] as MemoryType[],
+    maxMemories: 10,
+  },
+  autoCleanup: {
+    enabled: false,
+    maxAge: 90 * 24 * 60 * 60 * 1000,
+    minImportance: 0.3,
+  },
+  logging: {
+    enabled: true,
+    level: 'info',
+  },
+};
+
+export function validateConfig(config: Partial<AIMemoryConfig>): AIMemoryConfig {
+  const merged = { ...DEFAULT_CONFIG, ...config };
+
+  if (merged.maxMemories < 1) {
+    throw new Error('maxMemories must be at least 1');
+  }
+
+  if (merged.embeddingDimension < 1) {
+    throw new Error('embeddingDimension must be at least 1');
+  }
+
+  if (merged.context.maxTokens < 100) {
+    throw new Error('context.maxTokens must be at least 100');
+  }
+
+  if (merged.context.relevanceThreshold < 0 || merged.context.relevanceThreshold > 1) {
+    throw new Error('context.relevanceThreshold must be between 0 and 1');
+  }
+
+  return merged;
+}

package/src/contextBuilder.ts

@@ -0,0 +1,184 @@
+import { 
+  MemoryQuery, 
+  SearchResult, 
+  ContextConfig, 
+  ContextResult, 
+  ContextMessage,
+  MemoryType 
+} from './types.js';
+import { MemoryManager } from './memoryManager.js';
+
+export class ContextBuilder {
+  private memoryManager: MemoryManager;
+  private config: ContextConfig;
+
+  constructor(memoryManager: MemoryManager, config?: Partial<ContextConfig>) {
+    this.memoryManager = memoryManager;
+    this.config = {
+      maxTokens: 4000,
+      includeSystemPrompt: true,
+      systemPrompt: 'You are a helpful AI assistant with memory of past conversations and user preferences.',
+      relevanceThreshold: 0.7,
+      includeMetadata: false,
+      memoryTypes: ['conversation', 'fact', 'preference', 'context'],
+      maxMemories: 10,
+      ...config,
+    };
+  }
+
+  async buildContext(query: string, additionalConfig?: Partial<ContextConfig>): Promise<ContextResult> {
+    const config = { ...this.config, ...additionalConfig };
+    const messages: ContextMessage[] = [];
+    
+    if (config.includeSystemPrompt) {
+      messages.push({
+        role: 'system',
+        content: config.systemPrompt!,
+      });
+    }
+
+    const relevantMemories = await this.findRelevantMemories(query, config);
+    
+    const contextContent = this.buildContextContent(relevantMemories, config);
+    
+    if (contextContent) {
+      messages.push({
+        role: 'system',
+        content: contextContent,
+      });
+    }
+
+    const tokensEstimated = this.estimateTokens(messages);
+    const truncationApplied = tokensEstimated > config.maxTokens;
+
+    return {
+      messages,
+      memories: relevantMemories.map(r => r.memory),
+      stats: {
+        memoriesUsed: relevantMemories.length,
+        tokensEstimated,
+        truncationApplied,
+      },
+    };
+  }
+
+  private async findRelevantMemories(
+    query: string, 
+    config: ContextConfig
+  ): Promise<SearchResult[]> {
+    const searchQuery: MemoryQuery = {
+      text: query,
+      filter: {
+        types: config.memoryTypes,
+        minImportance: config.relevanceThreshold,
+      },
+      limit: config.maxMemories,
+      threshold: config.relevanceThreshold,
+    };
+
+    const results = await this.memoryManager.search(searchQuery);
+    
+    return results.filter(r => r.score >= config.relevanceThreshold);
+  }
+
+  private buildContextContent(memories: SearchResult[], config: ContextConfig): string {
+    if (memories.length === 0) return '';
+
+    const sections: string[] = [];
+    
+    const groupedByType = this.groupByType(memories);
+
+    if (groupedByType.fact && groupedByType.fact.length > 0) {
+      const facts = groupedByType.fact
+        .map(r => `- ${r.memory.content}`)
+        .join('\n');
+      sections.push(`Key Facts:\n${facts}`);
+    }
+
+    if (groupedByType.preference && groupedByType.preference.length > 0) {
+      const prefs = groupedByType.preference
+        .map(r => `- ${r.memory.content}`)
+        .join('\n');
+      sections.push(`User Preferences:\n${prefs}`);
+    }
+
+    if (groupedByType.conversation && groupedByType.conversation.length > 0) {
+      const recentConversations = groupedByType.conversation
+        .slice(0, 5)
+        .map(r => r.memory.content)
+        .join('\n');
+      sections.push(`Recent Conversation Context:\n${recentConversations}`);
+    }
+
+    if (groupedByType.context && groupedByType.context.length > 0) {
+      const context = groupedByType.context
+        .map(r => `- ${r.memory.content}`)
+        .join('\n');
+      sections.push(`Additional Context:\n${context}`);
+    }
+
+    if (groupedByType.instruction && groupedByType.instruction.length > 0) {
+      const instructions = groupedByType.instruction
+        .map(r => `- ${r.memory.content}`)
+        .join('\n');
+      sections.push(`Important Instructions:\n${instructions}`);
+    }
+
+    let content = sections.join('\n\n');
+
+    if (config.includeMetadata) {
+      const metadataList = memories
+        .map(r => `[${r.memory.metadata.type}] ${r.memory.metadata.tags.join(', ')}`)
+        .join('\n');
+      content += `\n\nMemory Metadata:\n${metadataList}`;
+    }
+
+    return content;
+  }
+
+  private groupByType(memories: SearchResult[]): Record<MemoryType, SearchResult[]> {
+    const grouped: Record<MemoryType, SearchResult[]> = {
+      conversation: [],
+      fact: [],
+      preference: [],
+      instruction: [],
+      context: [],
+      custom: [],
+    };
+
+    for (const result of memories) {
+      const type = result.memory.metadata.type;
+      if (grouped[type]) {
+        grouped[type].push(result);
+      }
+    }
+
+    return grouped;
+  }
+
+  private estimateTokens(messages: ContextMessage[]): number {
+    let total = 0;
+    
+    for (const message of messages) {
+      const words = message.content.split(/\s+/).length;
+      total += Math.ceil(words * 1.3);
+    }
+
+    return total;
+  }
+
+  updateConfig(config: Partial<ContextConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  getConfig(): Readonly<ContextConfig> {
+    return { ...this.config };
+  }
+}
+
+export function createContextBuilder(
+  memoryManager: MemoryManager, 
+  config?: Partial<ContextConfig>
+): ContextBuilder {
+  return new ContextBuilder(memoryManager, config);
+}