@veedubin/boomerang-v3 0.1.0

package/dist/memory/graph.js

@@ -0,0 +1,86 @@
+/**
+ * Memory graph integration for memini-ai
+ *
+ * Manages relationships between memory entries
+ */
+import { getClient } from '../memini-client/index.js';
+/**
+ * Find memories related to a given memory
+ */
+export async function findRelatedMemories(memoryId, relationshipType, limit = 10, client) {
+    const mc = client ?? getClient();
+    // findRelatedMemories returns MemoryEntry[], but API shows MemoryEntry[] directly
+    const entries = await mc.findRelatedMemories(memoryId, relationshipType, limit);
+    return entries.map((e) => ({
+        id: e.id,
+        text: e.text,
+        vector: Array.from(e.vector || []),
+        sourceType: reverseMapSourceType(e.sourceType),
+        sourcePath: e.sourcePath || '',
+        timestamp: e.timestamp,
+        contentHash: e.contentHash || '',
+    }));
+}
+/**
+ * Create a relationship between two memories
+ */
+export async function createRelationship(sourceId, targetId, type, confidence = 1.0, client) {
+    const mc = client ?? getClient();
+    await mc.createRelationship(sourceId, targetId, type, confidence);
+    return {
+        success: true,
+        sourceId,
+        targetId,
+        relationshipType: type,
+        confidence,
+    };
+}
+/**
+ * Get summary of all relationships for a memory
+ */
+export async function getRelationshipSummary(memoryId, client) {
+    const mc = client ?? getClient();
+    const result = await mc.getRelationshipSummary(memoryId);
+    if (!result) {
+        return {
+            memoryId,
+            totalRelationships: 0,
+            byType: {
+                SUPERSEDES: 0,
+                RELATED_TO: 0,
+                CONTRADICTS: 0,
+                DERIVED_FROM: 0,
+            },
+        };
+    }
+    // Ensure all relationship types are present
+    const allTypes = ['SUPERSEDES', 'RELATED_TO', 'CONTRADICTS', 'DERIVED_FROM'];
+    const completeByType = {};
+    for (const t of allTypes) {
+        completeByType[t] = result.byType?.[t] ?? 0;
+    }
+    return {
+        memoryId: result.memoryId,
+        totalRelationships: result.totalRelationships,
+        byType: completeByType,
+    };
+}
+/**
+ * Map memini-ai source type back to boomerang source type
+ */
+function reverseMapSourceType(type) {
+    switch (type) {
+        case 'session':
+            return 'conversation';
+        case 'file':
+            return 'file';
+        case 'web':
+            return 'web';
+        case 'boomerang':
+            return 'manual';
+        case 'project':
+            return 'manual';
+        default:
+            return type;
+    }
+}

package/dist/memory/index.js

@@ -0,0 +1,314 @@
+/**
+ * MemorySystem - Singleton wrapper for memini-ai MCP client
+ *
+ * Phase 1: Wraps memini-ai client while preserving the original API surface.
+ */
+import { initializeClient, } from '../memini-client/index.js';
+import { DEFAULT_SEARCH_OPTIONS } from './schema.js';
+const PROJECT_ID = process.env.BOOMERANG_PROJECT_ID || 'boomerang-default';
+class MemorySystem {
+    static instance = null;
+    _initialized = false;
+    _client = null;
+    _status = null;
+    constructor() { }
+    /**
+     * Get the MemorySystem singleton instance
+     */
+    static getInstance() {
+        if (!MemorySystem.instance) {
+            MemorySystem.instance = new MemorySystem();
+        }
+        return MemorySystem.instance;
+    }
+    /**
+     * Check if the system has been initialized
+     */
+    isInitialized() {
+        return this._initialized;
+    }
+    /**
+     * Initialize the memory system (lazy initialization)
+     * Connects to memini-ai Python MCP server
+     */
+    async initialize() {
+        if (this._initialized) {
+            return;
+        }
+        const pythonPath = process.env.PYTHON_PATH || 'python3';
+        const serverModule = process.env.MEMINI_SERVER_MODULE || 'memini_ai.server';
+        this._client = await initializeClient(pythonPath, serverModule);
+        // Get initial status
+        this._status = (await this._client.getStatus());
+        this._initialized = true;
+    }
+    /**
+     * Get the underlying MCP client
+     */
+    getClient() {
+        if (!this._client) {
+            throw new Error('MemorySystem not initialized. Call initialize() first.');
+        }
+        return this._client;
+    }
+    /**
+     * Add a new memory entry
+     */
+    async addMemory(entry) {
+        this.ensureInitialized();
+        // Map source type to memini-ai format
+        const sourceType = mapSourceType(entry.sourceType);
+        const result = await this._client.addMemory({
+            text: entry.text,
+            sourceType,
+            sourcePath: entry.sourcePath,
+            metadataJson: entry.metadataJson,
+        });
+        // result is already a MemoryEntry from memini-client
+        const meminiEntry = result;
+        return adaptMemoryEntry(meminiEntry);
+    }
+    /**
+     * Get a memory entry by ID
+     */
+    async getMemory(id) {
+        this.ensureInitialized();
+        // Search for the memory by ID
+        const results = await this._client.search(`id:${id}`, { topK: 1 });
+        const match = results.find((m) => m.entry.id === id);
+        if (match) {
+            return adaptMemoryEntry(match.entry);
+        }
+        return null;
+    }
+    /**
+     * Delete a memory entry by ID
+     * Note: memini-ai doesn't have direct delete, use adjustTrust with archive
+     */
+    async deleteMemory(id) {
+        this.ensureInitialized();
+        try {
+            // Archive the memory instead of deleting
+            await this._client.adjustTrust(id, 'agent_ignored');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * List unique source paths, optionally filtered by source type
+     */
+    async listSources(sourceType) {
+        this.ensureInitialized();
+        // This is a simplified implementation
+        // In production, you'd want a dedicated list_sources tool
+        const results = await this._client.search('', { topK: 100 });
+        const pathSet = new Set();
+        for (const result of results) {
+            const entry = result.entry;
+            const entrySourceType = reverseMapSourceType(entry.sourceType);
+            if (entry.sourcePath && (!sourceType || entrySourceType === sourceType)) {
+                pathSet.add(entry.sourcePath);
+            }
+        }
+        return Array.from(pathSet);
+    }
+    /**
+     * Save a context entry for a session
+     */
+    async saveContext(sessionId, context) {
+        this.ensureInitialized();
+        return this.addMemory({
+            text: context,
+            sourceType: 'conversation',
+            sourcePath: `session://${sessionId}`,
+            metadataJson: JSON.stringify({ type: 'context' }),
+            sessionId,
+        });
+    }
+    /**
+     * Get the most recent context entry for a session
+     */
+    async getContext(sessionId) {
+        this.ensureInitialized();
+        const results = await this._client.search(`session:${sessionId}`, { topK: 100 });
+        // Find the most recent context entry
+        let latestContext = null;
+        let latestTimestamp = 0;
+        for (const result of results) {
+            const entry = result.entry;
+            if (entry.metadataJson) {
+                try {
+                    const meta = JSON.parse(entry.metadataJson);
+                    if (meta.type === 'context') {
+                        const ts = entry.timestamp;
+                        if (ts > latestTimestamp) {
+                            latestTimestamp = ts;
+                            latestContext = adaptMemoryEntry(entry);
+                        }
+                    }
+                }
+                catch {
+                    // Not a context entry
+                }
+            }
+        }
+        return latestContext;
+    }
+    /**
+     * Search memories using query string with optional search options
+     */
+    async search(query, options) {
+        this.ensureInitialized();
+        const opts = {
+            ...DEFAULT_SEARCH_OPTIONS,
+            ...options,
+        };
+        const results = await this._client.search(query, { topK: opts.topK });
+        return results.map((r) => ({
+            entry: adaptMemoryEntry(r.entry),
+            score: r.score,
+        }));
+    }
+    /**
+     * Ensure the system is initialized before performing operations
+     */
+    ensureInitialized() {
+        if (!this.isInitialized()) {
+            throw new Error('MemorySystem not initialized. Call initialize() first.');
+        }
+    }
+    /**
+     * Get server status
+     */
+    async getStatus() {
+        if (!this._client) {
+            return null;
+        }
+        try {
+            this._status = (await this._client.getStatus());
+            return this._status;
+        }
+        catch {
+            return this._status;
+        }
+    }
+    /**
+     * Check if the memory system is ready
+     */
+    async isReady() {
+        const status = await this.getStatus();
+        return status?.memoryReady ?? false;
+    }
+    /**
+     * Check if content already exists (deduplication)
+     */
+    async contentExists(text) {
+        this.ensureInitialized();
+        const results = await this._client.search(text, { topK: 1 });
+        return results.length > 0;
+    }
+    /**
+     * Search memories using a pre-computed vector
+     * Note: memini-ai handles embedding internally
+     */
+    async searchWithVector(vector, options) {
+        this.ensureInitialized();
+        // memini-ai doesn't expose vector search directly
+        // Fall back to text search
+        const opts = {
+            ...DEFAULT_SEARCH_OPTIONS,
+            ...options,
+        };
+        // Use vector as seed for approximate search
+        const results = await this._client.search(`vector:${vector.slice(0, 10).join(',')}`, { topK: opts.topK });
+        return results.map((r) => ({
+            entry: adaptMemoryEntry(r.entry),
+            score: r.score,
+        }));
+    }
+    /**
+     * Get memories similar to a given memory
+     */
+    async getSimilar(memoryId, options) {
+        this.ensureInitialized();
+        const memory = await this.getMemory(memoryId);
+        if (!memory) {
+            return [];
+        }
+        return this.search(memory.text, options);
+    }
+    /**
+     * Get memory statistics
+     */
+    async getStats() {
+        this.ensureInitialized();
+        const status = await this.getStatus();
+        return {
+            count: status ? Object.keys(status).length : 0, // Placeholder
+        };
+    }
+}
+/**
+ * Map boomerang source type to memini-ai source type
+ */
+function mapSourceType(type) {
+    switch (type) {
+        case 'conversation':
+            return 'session';
+        case 'file':
+            return 'file';
+        case 'web':
+            return 'web';
+        case 'manual':
+            return 'boomerang';
+        default:
+            return 'boomerang';
+    }
+}
+/**
+ * Map memini-ai source type back to boomerang source type
+ */
+function reverseMapSourceType(type) {
+    switch (type) {
+        case 'session':
+            return 'conversation';
+        case 'file':
+            return 'file';
+        case 'web':
+            return 'web';
+        case 'boomerang':
+            return 'manual';
+        case 'project':
+            return 'manual';
+        default:
+            return type;
+    }
+}
+/**
+ * Adapt a raw memory from memini-ai to our MemoryEntry type
+ */
+function adaptMemoryEntry(meminiEntry) {
+    return {
+        id: meminiEntry.id,
+        text: meminiEntry.text,
+        vector: Array.from(meminiEntry.vector || []),
+        sourceType: reverseMapSourceType(meminiEntry.sourceType),
+        sourcePath: meminiEntry.sourcePath || '',
+        timestamp: meminiEntry.timestamp,
+        contentHash: meminiEntry.contentHash || '',
+        metadataJson: meminiEntry.metadataJson,
+        sessionId: meminiEntry.sessionId,
+        projectId: meminiEntry.projectId,
+        score: meminiEntry.score,
+        trustScore: meminiEntry.trustScore,
+    };
+}
+/**
+ * Factory function to get the MemorySystem singleton
+ */
+export function getMemorySystem() {
+    return MemorySystem.getInstance();
+}
+export { MemorySystem };

package/dist/memory/kg.js

@@ -0,0 +1,111 @@
+/**
+ * Knowledge graph integration for memini-ai (Phase 3)
+ *
+ * Entity extraction, graph queries, and inference chains
+ */
+import { getClient } from '../memini-client/index.js';
+/**
+ * Execute a formal knowledge graph query
+ */
+export async function queryKG(query, client) {
+    const mc = client ?? getClient();
+    const result = await mc.queryKG({
+        entity_a: query.entityA,
+        entity_b: query.entityB,
+        relationship_types: query.relationshipTypes,
+        inference_depth: query.inferenceDepth ?? 1,
+        limit: query.limit ?? 100,
+    });
+    if (!result) {
+        return {
+            success: false,
+            count: 0,
+            results: [],
+            error: 'Query failed',
+        };
+    }
+    return {
+        success: true,
+        count: result.entities.length,
+        results: result.entities,
+        error: undefined,
+    };
+}
+/**
+ * Extract entities from a specific memory
+ */
+export async function extractEntities(memoryId, client) {
+    const mc = client ?? getClient();
+    const result = await mc.extractEntities(memoryId);
+    return {
+        success: true,
+        memoryId,
+        entities: result.map((e) => ({
+            id: e.id,
+            name: e.name,
+            entityType: e.type ?? 'unknown',
+            metadata: e.properties ?? {},
+        })),
+        count: result.length,
+    };
+}
+/**
+ * Get all connections to/from an entity
+ */
+export async function getEntityGraph(entityId, depth = 1, client) {
+    const mc = client ?? getClient();
+    const result = await mc.getEntityGraph(entityId, depth);
+    if (!result) {
+        return null;
+    }
+    return {
+        entityId: result.entity.id,
+        incoming: result.connections.map((c) => c.target),
+        outgoing: result.connections.map((c) => c.target),
+        inferred: [],
+    };
+}
+/**
+ * Find inference paths between two entities
+ */
+export async function getInferenceChain(startEntity, endEntity, maxDepth = 3, client) {
+    const mc = client ?? getClient();
+    const result = await mc.getInferenceChain(startEntity, endEntity, maxDepth);
+    return {
+        success: true,
+        startEntity,
+        endEntity,
+        paths: result.map((p) => ({
+            path: p.path.map((step) => step.entity),
+            confidence: p.confidence,
+            depth: p.depth,
+        })),
+        count: result.length,
+        error: undefined,
+    };
+}
+/**
+ * Search for entities by name
+ */
+export async function searchEntities(name, limit = 10, client) {
+    const mc = client ?? getClient();
+    const result = await mc.searchEntities(name, limit);
+    return {
+        success: true,
+        query: name,
+        entities: result.map((e) => ({
+            id: e.id,
+            name: e.name,
+            entityType: e.type ?? 'unknown',
+            metadata: e.properties ?? {},
+        })),
+        count: result.length,
+    };
+}
+/**
+ * Get HTML visualization of the knowledge graph
+ */
+export async function getGraphVisualization(limit = 100, client) {
+    const mc = client ?? getClient();
+    return mc.getGraphVisualization(limit);
+}

package/dist/memory/schema.js

@@ -0,0 +1,10 @@
+/**
+ * Memory entry and search types for memini-ai integration
+ * Updated to include trust engine fields from memini-ai
+ */
+/** Default search options */
+export const DEFAULT_SEARCH_OPTIONS = {
+    strategy: 'tiered',
+    topK: 10,
+    threshold: 0.7,
+};

package/dist/memory/tiered.js

@@ -0,0 +1,104 @@
+/**
+ * Tiered loading integration for memini-ai
+ *
+ * L0: ~100 tokens - project summary for session start
+ * L1: ~2K tokens - key decisions for planning tasks
+ */
+import { getClient } from '../memini-client/index.js';
+/**
+ * Get L0 project summary (~100 tokens)
+ *
+ * Uses high-trust memories (trust >= 0.5) to generate a concise
+ * project summary suitable for session start auto-injection.
+ */
+export async function getTier0Summary(forceRefresh = false, client) {
+    const mc = client ?? getClient();
+    const result = await mc.getTier0Summary(forceRefresh);
+    if (!result) {
+        return {
+            tier: 'L0',
+            content: null,
+            tokenCount: 0,
+            cacheHit: false,
+            sourceCount: 0,
+            generatedAt: null,
+            error: 'Failed to generate summary',
+        };
+    }
+    return {
+        tier: 'L0',
+        content: result.content,
+        tokenCount: result.memoryCount,
+        cacheHit: false,
+        sourceCount: result.memoryCount,
+        generatedAt: result.generatedAt,
+        error: undefined,
+    };
+}
+/**
+ * Get L1 key decisions summary (~2K tokens)
+ *
+ * Uses promoted memories (trust >= 0.8) to generate a structured
+ * summary of key decisions and patterns for planning tasks.
+ */
+export async function getTier1Summary(forceRefresh = false, client) {
+    const mc = client ?? getClient();
+    const result = await mc.getTier1Summary(forceRefresh);
+    if (!result) {
+        return {
+            tier: 'L1',
+            content: null,
+            tokenCount: 0,
+            cacheHit: false,
+            sourceCount: 0,
+            generatedAt: null,
+            error: 'Failed to generate summary',
+        };
+    }
+    return {
+        tier: 'L1',
+        content: result.content,
+        tokenCount: result.memoryCount,
+        cacheHit: false,
+        sourceCount: result.memoryCount,
+        generatedAt: result.generatedAt,
+        error: undefined,
+    };
+}
+/**
+ * Trigger memory extraction manually
+ *
+ * Extracts facts/decisions/preferences from conversation text
+ * using LLM-based automatic extraction.
+ */
+export async function triggerExtraction(conversation, client) {
+    const mc = client ?? getClient();
+    const result = await mc.triggerExtraction(conversation);
+    return {
+        success: true,
+        count: result.length,
+        memoryIds: result,
+    };
+}
+/**
+ * Pre-compression extraction
+ *
+ * Captures current context and extracts memories before context
+ * compression/compaction. Helps preserve important details.
+ */
+export async function preconpressExtraction(context, client) {
+    const mc = client ?? getClient();
+    const result = await mc.preconpressExtraction(context);
+    if (!result) {
+        return {
+            extractionCount: 0,
+            memoriesCreated: [],
+            contextCaptured: context ?? '',
+        };
+    }
+    return {
+        extractionCount: result.extractedMemories.length,
+        memoriesCreated: result.extractedMemories,
+        contextCaptured: context ?? '',
+    };
+}