server-memory-enhanced 0.2.0 → 2.1.0

package/dist/lib/constants.js

@@ -0,0 +1,55 @@
+/**
+ * Constants for validation rules
+ * Centralized to follow DRY principle and make maintenance easier
+ */
+/**
+ * Maximum length for observations in characters
+ * Per spec Section 2: Hard Limits on Observation Length
+ */
+export const MAX_OBSERVATION_LENGTH = 150;
+/**
+ * Maximum number of sentences allowed per observation
+ * Per spec Section 2: Hard Limits on Observation Length
+ */
+export const MAX_SENTENCES = 2;
+/**
+ * Minimum observation length in characters
+ */
+export const MIN_OBSERVATION_LENGTH = 5;
+/**
+ * Minimum entity name length
+ */
+export const MIN_ENTITY_NAME_LENGTH = 1;
+/**
+ * Maximum entity name length
+ */
+export const MAX_ENTITY_NAME_LENGTH = 100;
+/**
+ * Minimum entity type length
+ */
+export const MIN_ENTITY_TYPE_LENGTH = 1;
+/**
+ * Maximum entity type length
+ */
+export const MAX_ENTITY_TYPE_LENGTH = 50;
+/**
+ * Target average relations per entity for quality scoring
+ * Used to normalize relation count to 0-1 scale
+ */
+export const TARGET_AVG_RELATIONS = 2;
+/**
+ * Weight for relation score in quality calculation
+ */
+export const RELATION_SCORE_WEIGHT = 0.7;
+/**
+ * Weight for observation score in quality calculation
+ */
+export const OBSERVATION_SCORE_WEIGHT = 0.3;
+/**
+ * Maximum number of entities returned in analytics queries
+ */
+export const ANALYTICS_RESULT_LIMIT = 10;
+/**
+ * Sentence terminators used for counting sentences
+ */
+export const SENTENCE_TERMINATORS = /[.!?]/;

package/dist/lib/jsonl-storage-adapter.js

@@ -0,0 +1,315 @@
+/**
+ * JSONL Storage Adapter - implements file-based storage using JSON Lines format
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+// Constants for file naming and types
+const THREAD_FILE_PREFIX = 'thread-';
+const THREAD_FILE_EXTENSION = '.jsonl';
+const ENTITY_TYPE = 'entity';
+const RELATION_TYPE = 'relation';
+const FILE_NOT_FOUND_ERROR = 'ENOENT';
+/**
+ * Type guard to check if an error is a FileSystemError
+ */
+function isFileSystemError(error) {
+    return error instanceof Error && 'code' in error;
+}
+/**
+ * Check if a string field is valid (non-empty after trimming)
+ */
+function isValidString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * JSONL-based storage adapter for the knowledge graph
+ * Stores data in thread-specific JSONL files
+ *
+ * Responsibilities:
+ * - File I/O operations for JSONL format
+ * - Thread-based data organization
+ * - Data serialization/deserialization
+ */
+export class JsonlStorageAdapter {
+    memoryDirPath;
+    constructor(memoryDirPath) {
+        this.memoryDirPath = memoryDirPath;
+    }
+    /**
+     * Get the file path for a specific thread
+     */
+    getThreadFilePath(agentThreadId) {
+        return path.join(this.memoryDirPath, `${THREAD_FILE_PREFIX}${agentThreadId}${THREAD_FILE_EXTENSION}`);
+    }
+    /**
+     * Check if an item is a valid entity
+     */
+    isValidEntity(item) {
+        return item.type === ENTITY_TYPE &&
+            isValidString(item.name) &&
+            isValidString(item.entityType) &&
+            Array.isArray(item.observations) &&
+            isValidString(item.agentThreadId) &&
+            isValidString(item.timestamp) &&
+            typeof item.confidence === 'number' &&
+            typeof item.importance === 'number';
+    }
+    /**
+     * Check if an item is a valid relation
+     */
+    isValidRelation(item) {
+        return item.type === RELATION_TYPE &&
+            isValidString(item.from) &&
+            isValidString(item.to) &&
+            isValidString(item.relationType) &&
+            isValidString(item.agentThreadId) &&
+            isValidString(item.timestamp) &&
+            typeof item.confidence === 'number' &&
+            typeof item.importance === 'number';
+    }
+    /**
+     * Parse and validate a single JSONL line
+     */
+    parseLine(line, filePath) {
+        try {
+            return JSON.parse(line);
+        }
+        catch (parseError) {
+            console.warn(`Skipping malformed JSON line in ${filePath} (line length: ${line.length} chars)`);
+            return null;
+        }
+    }
+    /**
+     * Convert JSONL item to Entity
+     */
+    toEntity(item) {
+        return {
+            name: item.name,
+            entityType: item.entityType,
+            observations: item.observations,
+            agentThreadId: item.agentThreadId,
+            timestamp: item.timestamp,
+            confidence: item.confidence,
+            importance: item.importance
+        };
+    }
+    /**
+     * Convert JSONL item to Relation
+     */
+    toRelation(item) {
+        return {
+            from: item.from,
+            to: item.to,
+            relationType: item.relationType,
+            agentThreadId: item.agentThreadId,
+            timestamp: item.timestamp,
+            confidence: item.confidence,
+            importance: item.importance
+        };
+    }
+    /**
+     * Process a single JSONL item and add to graph
+     */
+    processItem(item, graph, filePath) {
+        if (!item) {
+            return;
+        }
+        if (this.isValidEntity(item)) {
+            graph.entities.push(this.toEntity(item));
+        }
+        else if (this.isValidRelation(item)) {
+            graph.relations.push(this.toRelation(item));
+        }
+        else if (item.type === ENTITY_TYPE || item.type === RELATION_TYPE) {
+            console.warn(`Skipping ${item.type} with missing required fields in ${filePath}`);
+        }
+    }
+    /**
+     * Serialize an entity to JSONL format
+     */
+    serializeEntity(entity) {
+        return JSON.stringify({
+            type: ENTITY_TYPE,
+            name: entity.name,
+            entityType: entity.entityType,
+            observations: entity.observations,
+            agentThreadId: entity.agentThreadId,
+            timestamp: entity.timestamp,
+            confidence: entity.confidence,
+            importance: entity.importance
+        });
+    }
+    /**
+     * Serialize a relation to JSONL format
+     */
+    serializeRelation(relation) {
+        return JSON.stringify({
+            type: RELATION_TYPE,
+            from: relation.from,
+            to: relation.to,
+            relationType: relation.relationType,
+            agentThreadId: relation.agentThreadId,
+            timestamp: relation.timestamp,
+            confidence: relation.confidence,
+            importance: relation.importance
+        });
+    }
+    /**
+     * Get or create thread data in the map
+     */
+    getOrCreateThreadData(threadMap, threadId) {
+        let threadData = threadMap.get(threadId);
+        if (!threadData) {
+            threadData = { entities: [], relations: [] };
+            threadMap.set(threadId, threadData);
+        }
+        return threadData;
+    }
+    /**
+     * Check if error is a file not found error
+     */
+    isFileNotFoundError(error) {
+        return isFileSystemError(error) && error.code === FILE_NOT_FOUND_ERROR;
+    }
+    /**
+     * Extract thread ID from filename
+     */
+    extractThreadId(fileName) {
+        const match = fileName.match(new RegExp(`^${THREAD_FILE_PREFIX}(.+)${THREAD_FILE_EXTENSION}$`));
+        return match ? match[1] : null;
+    }
+    /**
+     * Load graph data from a single JSONL file
+     */
+    async loadGraphFromFile(filePath) {
+        try {
+            const data = await fs.readFile(filePath, "utf-8");
+            const lines = data.split("\n").filter(line => line.trim() !== "");
+            const graph = { entities: [], relations: [] };
+            for (const line of lines) {
+                const item = this.parseLine(line, filePath);
+                this.processItem(item, graph, filePath);
+            }
+            return graph;
+        }
+        catch (error) {
+            if (this.isFileNotFoundError(error)) {
+                return { entities: [], relations: [] };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get all thread file names in the memory directory
+     */
+    async getThreadFileNames() {
+        const files = await fs.readdir(this.memoryDirPath).catch(() => []);
+        return files.filter(f => f.startsWith(THREAD_FILE_PREFIX) && f.endsWith(THREAD_FILE_EXTENSION));
+    }
+    /**
+     * Merge multiple graphs into one
+     */
+    mergeGraphs(graphs) {
+        return graphs.reduce((acc, graph) => ({
+            entities: [...acc.entities, ...graph.entities],
+            relations: [...acc.relations, ...graph.relations]
+        }), { entities: [], relations: [] });
+    }
+    /**
+     * Load the complete knowledge graph from all thread files
+     */
+    async loadGraph() {
+        const threadFiles = await this.getThreadFileNames();
+        const graphs = await Promise.all(threadFiles.map(f => this.loadGraphFromFile(path.join(this.memoryDirPath, f))));
+        return this.mergeGraphs(graphs);
+    }
+    /**
+     * Delete empty thread file if it exists
+     */
+    async deleteThreadFileIfExists(threadFilePath) {
+        try {
+            await fs.unlink(threadFilePath);
+        }
+        catch (error) {
+            if (!this.isFileNotFoundError(error)) {
+                console.warn(`Failed to delete empty thread file ${threadFilePath}:`, error);
+            }
+        }
+    }
+    /**
+     * Serialize thread data to JSONL lines
+     */
+    serializeThreadData(threadData) {
+        return [
+            ...threadData.entities.map(e => this.serializeEntity(e)),
+            ...threadData.relations.map(r => this.serializeRelation(r))
+        ];
+    }
+    /**
+     * Save data for a specific thread
+     */
+    async saveGraphForThread(agentThreadId, threadData) {
+        const threadFilePath = this.getThreadFilePath(agentThreadId);
+        const lines = this.serializeThreadData(threadData);
+        if (lines.length === 0) {
+            await this.deleteThreadFileIfExists(threadFilePath);
+            return;
+        }
+        await fs.writeFile(threadFilePath, lines.join("\n"));
+    }
+    /**
+     * Group graph data by thread ID
+     */
+    groupByThread(graph) {
+        const threadMap = new Map();
+        for (const entity of graph.entities) {
+            const threadData = this.getOrCreateThreadData(threadMap, entity.agentThreadId);
+            threadData.entities.push(entity);
+        }
+        for (const relation of graph.relations) {
+            const threadData = this.getOrCreateThreadData(threadMap, relation.agentThreadId);
+            threadData.relations.push(relation);
+        }
+        return threadMap;
+    }
+    /**
+     * Save all thread data to their respective files
+     */
+    async saveAllThreads(threadMap) {
+        const savePromises = Array.from(threadMap.entries()).map(([threadId, data]) => this.saveGraphForThread(threadId, data));
+        await Promise.all(savePromises);
+    }
+    /**
+     * Clean up stale thread files that are no longer in the graph
+     */
+    async cleanupStaleThreadFiles(activeThreadIds) {
+        try {
+            const threadFiles = await this.getThreadFileNames();
+            const deletePromises = threadFiles.map(async (fileName) => {
+                const threadId = this.extractThreadId(fileName);
+                if (threadId && !activeThreadIds.has(threadId)) {
+                    const filePath = path.join(this.memoryDirPath, fileName);
+                    await this.deleteThreadFileIfExists(filePath);
+                }
+            });
+            await Promise.all(deletePromises);
+        }
+        catch (error) {
+            console.warn('Failed to clean up stale thread files:', error);
+        }
+    }
+    /**
+     * Save the complete knowledge graph to thread-specific files
+     */
+    async saveGraph(graph) {
+        const threadMap = this.groupByThread(graph);
+        await this.saveAllThreads(threadMap);
+        await this.cleanupStaleThreadFiles(new Set(threadMap.keys()));
+    }
+    /**
+     * Initialize the storage adapter (create memory directory if needed)
+     */
+    async initialize() {
+        await fs.mkdir(this.memoryDirPath, { recursive: true });
+    }
+}