confused-ai-core 0.1.0

package/src/memory/in-memory-store.ts

@@ -0,0 +1,255 @@
+/**
+ * In-memory memory store implementation
+ */
+
+import {
+    MemoryStore,
+    MemoryEntry,
+    MemoryQuery,
+    MemoryFilter,
+    MemoryType,
+    MemorySearchResult,
+    MemoryStoreConfig,
+} from './types.js';
+import type { EntityId } from '../core/types.js';
+import { DebugLogger, createDebugLogger } from '../debug-logger.js';
+
+/**
+ * Default configuration for in-memory store
+ */
+const DEFAULT_CONFIG: Required<MemoryStoreConfig> = {
+    maxShortTermEntries: 100,
+    defaultQueryLimit: 10,
+    similarityThreshold: 0.7,
+    embeddingDimension: 1536,
+    debug: false,
+};
+
+/**
+ * In-memory implementation of MemoryStore
+ * Suitable for development and testing
+ */
+export class InMemoryStore implements MemoryStore {
+    private memories: Map<EntityId, MemoryEntry> = new Map();
+    private config: Required<MemoryStoreConfig>;
+    private logger: DebugLogger;
+
+    constructor(config: MemoryStoreConfig = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.logger = createDebugLogger('MemoryStore', this.config.debug);
+        this.logger.debug('InMemoryStore initialized', undefined, this.config);
+    }
+
+    async store(entry: Omit<MemoryEntry, 'id' | 'createdAt'>): Promise<MemoryEntry> {
+        const id = this.generateId();
+        const createdAt = new Date();
+
+        const fullEntry: MemoryEntry = {
+            ...entry,
+            id,
+            createdAt,
+        };
+
+        this.memories.set(id, fullEntry);
+        this.logger.debug('Stored memory entry', undefined, {
+            id,
+            type: entry.type,
+            tags: entry.metadata.tags,
+            agentId: entry.metadata.agentId,
+            sessionId: entry.metadata.sessionId,
+        });
+
+        // Enforce short-term memory limits
+        if (entry.type === MemoryType.SHORT_TERM) {
+            this.enforceShortTermLimit();
+        }
+
+        return fullEntry;
+    }
+
+    async retrieve(query: MemoryQuery): Promise<MemorySearchResult[]> {
+        const limit = query.limit ?? this.config.defaultQueryLimit;
+        const threshold = query.threshold ?? this.config.similarityThreshold;
+
+        let entries = Array.from(this.memories.values());
+
+        // Filter by type
+        if (query.type) {
+            entries = entries.filter(e => e.type === query.type);
+        }
+
+        // Apply filters
+        if (query.filter) {
+            entries = this.applyFilter(entries, query.filter);
+        }
+
+        // Calculate similarity scores (simplified - just keyword matching for in-memory)
+        const scored = entries.map(entry => ({
+            entry,
+            score: this.calculateSimilarity(query.query, entry.content),
+        }));
+
+        // Filter by threshold and sort by score
+        const results = scored
+            .filter(r => r.score >= threshold)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+
+        this.logger.debug('Retrieved memory results', undefined, {
+            query: query.query.slice(0, 50),
+            type: query.type,
+            filter: query.filter,
+            totalMatches: results.length,
+            limit: limit,
+            threshold: threshold,
+        });
+
+        return results;
+    }
+
+    async get(id: EntityId): Promise<MemoryEntry | null> {
+        const entry = this.memories.get(id) ?? null;
+        if (entry) {
+            this.logger.debug('Retrieved memory entry', undefined, { id, type: entry.type });
+        } else {
+            this.logger.debug('Memory entry not found', undefined, { id });
+        }
+        return entry;
+    }
+
+    async update(
+        id: EntityId,
+        updates: Partial<Omit<MemoryEntry, 'id' | 'createdAt'>>
+    ): Promise<MemoryEntry> {
+        const existing = this.memories.get(id);
+        if (!existing) {
+            throw new Error(`Memory entry not found: ${id}`);
+        }
+
+        const updated: MemoryEntry = {
+            ...existing,
+            ...updates,
+            id: existing.id,
+            createdAt: existing.createdAt,
+        };
+
+        this.memories.set(id, updated);
+        return updated;
+    }
+
+    async delete(id: EntityId): Promise<boolean> {
+        return this.memories.delete(id);
+    }
+
+    async clear(type?: MemoryType): Promise<void> {
+        if (type) {
+            for (const [id, entry] of this.memories) {
+                if (entry.type === type) {
+                    this.memories.delete(id);
+                }
+            }
+        } else {
+            this.memories.clear();
+        }
+    }
+
+    async getRecent(limit: number, type?: MemoryType): Promise<MemoryEntry[]> {
+        let entries = Array.from(this.memories.values());
+
+        if (type) {
+            entries = entries.filter(e => e.type === type);
+        }
+
+        return entries
+            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+            .slice(0, limit);
+    }
+
+    async snapshot(): Promise<MemoryEntry[]> {
+        return Array.from(this.memories.values());
+    }
+
+    /**
+     * Get the number of stored memories
+     */
+    size(): number {
+        return this.memories.size;
+    }
+
+    /**
+     * Generate a unique ID
+     */
+    private generateId(): EntityId {
+        return `mem-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+
+    /**
+     * Apply filter to memory entries
+     */
+    private applyFilter(entries: MemoryEntry[], filter: MemoryFilter): MemoryEntry[] {
+        return entries.filter(entry => {
+            if (filter.tags && filter.tags.length > 0) {
+                const entryTags = entry.metadata.tags ?? [];
+                if (!filter.tags.some(tag => entryTags.includes(tag))) {
+                    return false;
+                }
+            }
+
+            if (filter.source && entry.metadata.source !== filter.source) {
+                return false;
+            }
+
+            if (filter.agentId && entry.metadata.agentId !== filter.agentId) {
+                return false;
+            }
+
+            if (filter.sessionId && entry.metadata.sessionId !== filter.sessionId) {
+                return false;
+            }
+
+            if (filter.before && entry.createdAt > filter.before) {
+                return false;
+            }
+
+            if (filter.after && entry.createdAt < filter.after) {
+                return false;
+            }
+
+            return true;
+        });
+    }
+
+    /**
+     * Calculate simple similarity score between query and content
+     * In production, use proper embeddings
+     */
+    private calculateSimilarity(query: string, content: string): number {
+        const queryWords = query.toLowerCase().split(/\s+/);
+        const contentWords = content.toLowerCase().split(/\s+/);
+
+        let matches = 0;
+        for (const word of queryWords) {
+            if (contentWords.some(cw => cw.includes(word) || word.includes(cw))) {
+                matches++;
+            }
+        }
+
+        return matches / Math.max(queryWords.length, 1);
+    }
+
+    /**
+     * Enforce short-term memory entry limit
+     */
+    private enforceShortTermLimit(): void {
+        const shortTermEntries = Array.from(this.memories.values())
+            .filter(e => e.type === MemoryType.SHORT_TERM)
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+
+        const excess = shortTermEntries.length - this.config.maxShortTermEntries;
+        if (excess > 0) {
+            for (let i = 0; i < excess; i++) {
+                this.memories.delete(shortTermEntries[i].id);
+            }
+        }
+    }
+}

package/src/memory/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Memory module exports
+ */
+
+export * from './types.js';
+export { InMemoryStore } from './in-memory-store.js';
+export { VectorMemoryStore } from './vector-store.js';

package/src/memory/types.ts

@@ -0,0 +1,193 @@
+/**
+ * Memory store types and interfaces
+ */
+
+import type { EntityId } from '../core/types.js';
+
+/**
+ * Types of memory supported
+ */
+export enum MemoryType {
+    SHORT_TERM = 'short_term',
+    LONG_TERM = 'long_term',
+    EPISODIC = 'episodic',
+    SEMANTIC = 'semantic',
+}
+
+/**
+ * A memory entry
+ */
+export interface MemoryEntry {
+    readonly id: EntityId;
+    readonly type: MemoryType;
+    readonly content: string;
+    readonly embedding?: number[];
+    readonly metadata: MemoryMetadata;
+    readonly createdAt: Date;
+    readonly expiresAt?: Date;
+}
+
+/**
+ * Metadata for memory entries
+ */
+export interface MemoryMetadata {
+    readonly source?: string;
+    readonly importance?: number;
+    readonly tags?: string[];
+    readonly agentId?: EntityId;
+    readonly sessionId?: string;
+    readonly custom?: Record<string, unknown>;
+}
+
+/**
+ * Query options for memory retrieval
+ */
+export interface MemoryQuery {
+    readonly query: string;
+    readonly type?: MemoryType;
+    readonly limit?: number;
+    readonly threshold?: number;
+    readonly filter?: MemoryFilter;
+    readonly includeEmbeddings?: boolean;
+}
+
+/**
+ * Filter for memory queries
+ */
+export interface MemoryFilter {
+    readonly tags?: string[];
+    readonly source?: string;
+    readonly agentId?: EntityId;
+    readonly sessionId?: string;
+    readonly before?: Date;
+    readonly after?: Date;
+    readonly custom?: Record<string, unknown>;
+}
+
+/**
+ * Configuration for memory store
+ */
+export interface MemoryStoreConfig {
+    readonly maxShortTermEntries?: number;
+    readonly defaultQueryLimit?: number;
+    readonly similarityThreshold?: number;
+    readonly embeddingDimension?: number;
+    /** Enable debug logging */
+    readonly debug?: boolean;
+}
+
+/**
+ * Result from memory search
+ */
+export interface MemorySearchResult {
+    readonly entry: MemoryEntry;
+    readonly score: number;
+}
+
+/**
+ * Abstract memory store interface
+ */
+export interface MemoryStore {
+    /**
+     * Store a new memory entry
+     */
+    store(entry: Omit<MemoryEntry, 'id' | 'createdAt'>): Promise<MemoryEntry>;
+
+    /**
+     * Retrieve memories by query (semantic search)
+     */
+    retrieve(query: MemoryQuery): Promise<MemorySearchResult[]>;
+
+    /**
+     * Get a specific memory by ID
+     */
+    get(id: EntityId): Promise<MemoryEntry | null>;
+
+    /**
+     * Update an existing memory
+     */
+    update(id: EntityId, updates: Partial<Omit<MemoryEntry, 'id' | 'createdAt'>>): Promise<MemoryEntry>;
+
+    /**
+     * Delete a memory by ID
+     */
+    delete(id: EntityId): Promise<boolean>;
+
+    /**
+     * Clear all memories (optionally filtered by type)
+     */
+    clear(type?: MemoryType): Promise<void>;
+
+    /**
+     * Get recent memories
+     */
+    getRecent(limit: number, type?: MemoryType): Promise<MemoryEntry[]>;
+
+    /**
+     * Create a snapshot of current memories
+     */
+    snapshot(): Promise<MemoryEntry[]>;
+}
+
+/**
+ * Embedding provider interface for vector operations
+ */
+export interface EmbeddingProvider {
+    /**
+     * Generate embeddings for text
+     */
+    embed(text: string): Promise<number[]>;
+
+    /**
+     * Generate embeddings for multiple texts
+     */
+    embedBatch(texts: string[]): Promise<number[][]>;
+
+    /**
+     * Get the dimension of embeddings
+     */
+    getDimension(): number;
+}
+
+/**
+ * Vector store adapter interface
+ */
+export interface VectorStoreAdapter {
+    /**
+     * Store vectors with metadata
+     */
+    upsert(vectors: VectorEntry[]): Promise<void>;
+
+    /**
+     * Search for similar vectors
+     */
+    search(query: number[], limit: number, filter?: Record<string, unknown>): Promise<VectorSearchResult[]>;
+
+    /**
+     * Delete vectors by ID
+     */
+    delete(ids: EntityId[]): Promise<void>;
+
+    /**
+     * Clear all vectors
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Vector entry for storage
+ */
+export interface VectorEntry {
+    readonly id: EntityId;
+    readonly vector: number[];
+    readonly metadata: Record<string, unknown>;
+}
+
+/**
+ * Vector search result
+ */
+export interface VectorSearchResult {
+    readonly id: EntityId;
+    readonly score: number;
+    readonly metadata: Record<string, unknown>;
+}

package/src/memory/vector-store.ts

@@ -0,0 +1,251 @@
+/**
+ * Vector-based memory store implementation
+ */
+
+import {
+    MemoryStore,
+    MemoryEntry,
+    MemoryQuery,
+    MemoryFilter,
+    MemoryType,
+    MemorySearchResult,
+    MemoryStoreConfig,
+    VectorStoreAdapter,
+    EmbeddingProvider,
+} from './types.js';
+import type { EntityId } from '../core/types.js';
+
+/**
+ * Configuration for vector memory store
+ */
+export interface VectorMemoryStoreConfig extends MemoryStoreConfig {
+    vectorStore: VectorStoreAdapter;
+    embeddingProvider: EmbeddingProvider;
+}
+
+/**
+ * Vector-based memory store using external vector database
+ */
+export class VectorMemoryStore implements MemoryStore {
+    private config: Required<MemoryStoreConfig>;
+    private vectorStore: VectorStoreAdapter;
+    private embeddingProvider: EmbeddingProvider;
+    private entryCache: Map<EntityId, MemoryEntry> = new Map();
+
+    constructor(config: VectorMemoryStoreConfig) {
+        this.vectorStore = config.vectorStore;
+        this.embeddingProvider = config.embeddingProvider;
+        this.config = {
+            maxShortTermEntries: config.maxShortTermEntries ?? 100,
+            defaultQueryLimit: config.defaultQueryLimit ?? 10,
+            similarityThreshold: config.similarityThreshold ?? 0.7,
+            embeddingDimension: config.embeddingDimension ?? this.embeddingProvider.getDimension(),
+            debug: config.debug ?? false,
+        };
+    }
+
+    async store(entry: Omit<MemoryEntry, 'id' | 'createdAt'>): Promise<MemoryEntry> {
+        const id = this.generateId();
+        const createdAt = new Date();
+
+        // Generate embedding for the content
+        const embedding = await this.embeddingProvider.embed(entry.content);
+
+        const fullEntry: MemoryEntry = {
+            ...entry,
+            id,
+            createdAt,
+            embedding,
+        };
+
+        // Store in vector database
+        await this.vectorStore.upsert([
+            {
+                id,
+                vector: embedding,
+                metadata: {
+                    type: entry.type,
+                    content: entry.content,
+                    createdAt: createdAt.toISOString(),
+                    ...entry.metadata,
+                },
+            },
+        ]);
+
+        // Cache locally
+        this.entryCache.set(id, fullEntry);
+
+        return fullEntry;
+    }
+
+    async retrieve(query: MemoryQuery): Promise<MemorySearchResult[]> {
+        const limit = query.limit ?? this.config.defaultQueryLimit;
+
+        // Generate embedding for the query
+        const queryEmbedding = await this.embeddingProvider.embed(query.query);
+
+        // Build filter for vector store
+        const filter: Record<string, unknown> = {};
+        if (query.type) {
+            filter.type = query.type;
+        }
+        if (query.filter) {
+            Object.assign(filter, this.convertFilter(query.filter));
+        }
+
+        // Search vector store
+        const results = await this.vectorStore.search(queryEmbedding, limit, filter);
+
+        // Convert to MemorySearchResult
+        return results.map(r => {
+            const entry = this.entryCache.get(r.id) ?? this.reconstructEntry(r.id, r.metadata);
+            return {
+                entry,
+                score: r.score,
+            };
+        });
+    }
+
+    async get(id: EntityId): Promise<MemoryEntry | null> {
+        // Check cache first
+        const cached = this.entryCache.get(id);
+        if (cached) {
+            return cached;
+        }
+
+        // Would need to implement get by ID in vector store
+        // For now, return null
+        return null;
+    }
+
+    async update(
+        id: EntityId,
+        updates: Partial<Omit<MemoryEntry, 'id' | 'createdAt'>>
+    ): Promise<MemoryEntry> {
+        const existing = await this.get(id);
+        if (!existing) {
+            throw new Error(`Memory entry not found: ${id}`);
+        }
+
+        // If content is updated, regenerate embedding
+        let embedding = existing.embedding;
+        if (updates.content && updates.content !== existing.content) {
+            embedding = await this.embeddingProvider.embed(updates.content);
+        }
+
+        const updated: MemoryEntry = {
+            ...existing,
+            ...updates,
+            id: existing.id,
+            createdAt: existing.createdAt,
+            embedding: embedding ?? existing.embedding,
+        };
+
+        // Update in vector store
+        await this.vectorStore.upsert([
+            {
+                id,
+                vector: updated.embedding ?? [],
+                metadata: {
+                    type: updated.type,
+                    content: updated.content,
+                    createdAt: updated.createdAt.toISOString(),
+                    ...updated.metadata,
+                },
+            },
+        ]);
+
+        // Update cache
+        this.entryCache.set(id, updated);
+
+        return updated;
+    }
+
+    async delete(id: EntityId): Promise<boolean> {
+        await this.vectorStore.delete([id]);
+        this.entryCache.delete(id);
+        return true;
+    }
+
+    async clear(type?: MemoryType): Promise<void> {
+        if (type) {
+            // Vector stores typically don't support clearing by metadata filter
+            // This would need to be implemented in the adapter
+            const allEntries = Array.from(this.entryCache.values());
+            const toDelete = allEntries.filter(e => e.type === type).map(e => e.id);
+            await this.vectorStore.delete(toDelete);
+            for (const id of toDelete) {
+                this.entryCache.delete(id);
+            }
+        } else {
+            await this.vectorStore.clear();
+            this.entryCache.clear();
+        }
+    }
+
+    async getRecent(limit: number, type?: MemoryType): Promise<MemoryEntry[]> {
+        // Get all cached entries sorted by date
+        let entries = Array.from(this.entryCache.values());
+
+        if (type) {
+            entries = entries.filter(e => e.type === type);
+        }
+
+        return entries
+            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+            .slice(0, limit);
+    }
+
+    async snapshot(): Promise<MemoryEntry[]> {
+        return Array.from(this.entryCache.values());
+    }
+
+    /**
+     * Generate a unique ID
+     */
+    private generateId(): EntityId {
+        return `vec-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+
+    /**
+     * Convert memory filter to vector store filter
+     */
+    private convertFilter(filter: MemoryFilter): Record<string, unknown> {
+        const result: Record<string, unknown> = {};
+
+        if (filter.tags) {
+            result.tags = filter.tags;
+        }
+        if (filter.source) {
+            result.source = filter.source;
+        }
+        if (filter.agentId) {
+            result.agentId = filter.agentId;
+        }
+        if (filter.sessionId) {
+            result.sessionId = filter.sessionId;
+        }
+
+        return result;
+    }
+
+    /**
+     * Reconstruct a memory entry from vector store metadata
+     */
+    private reconstructEntry(id: EntityId, metadata: Record<string, unknown>): MemoryEntry {
+        return {
+            id,
+            type: (metadata.type as MemoryType) ?? MemoryType.SHORT_TERM,
+            content: (metadata.content as string) ?? '',
+            metadata: {
+                source: metadata.source as string,
+                importance: metadata.importance as number,
+                tags: metadata.tags as string[],
+                agentId: metadata.agentId as EntityId,
+                sessionId: metadata.sessionId as string,
+                custom: metadata.custom as Record<string, unknown>,
+            },
+            createdAt: new Date(metadata.createdAt as string),
+        };
+    }
+}