mindforge-sdk 10.7.0

package/dist/memory.js

@@ -0,0 +1,628 @@
+"use strict";
+/**
+ * MindForge v2.4.0 SDK — Memory API (RAG 2.0)
+ * Self-contained TypeScript interface to the MindForge Knowledge Graph.
+ *
+ * This module is fully standalone — it reads/writes JSONL files directly
+ * without depending on bin/ internal modules.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MindForgeMemory = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+// ── Internal Helpers ──────────────────────────────────────────────────────────
+function ensureDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+function readJsonlFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+    const byId = new Map();
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            byId.set(entry.id, entry); // Last write wins (append-only pattern)
+        }
+        catch {
+            // Skip malformed lines — never crash on corrupt JSONL
+        }
+    }
+    return [...byId.values()];
+}
+function appendJsonl(filePath, data) {
+    ensureDir(path.dirname(filePath));
+    fs.appendFileSync(filePath, JSON.stringify(data) + '\n');
+}
+function generateId() {
+    return crypto.randomUUID();
+}
+function computeChecksum(data) {
+    const payload = JSON.stringify(data, Object.keys(data).sort());
+    return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+function scoreRelevance(entry, tags, topic) {
+    let score = entry.confidence;
+    // Tag overlap
+    const entryTags = entry.tags || [];
+    const tagOverlap = tags.filter(t => entryTags.some(et => et.toLowerCase() === t.toLowerCase())).length;
+    score += tagOverlap * 0.2;
+    // Topic text match
+    if (topic) {
+        const topicWords = topic.toLowerCase().split(/\s+/);
+        const entryText = `${entry.topic} ${entry.content}`.toLowerCase();
+        const wordMatches = topicWords.filter(w => w.length > 3 && entryText.includes(w)).length;
+        score += (wordMatches / Math.max(topicWords.length, 1)) * 0.3;
+    }
+    // Recency boost
+    if (entry.last_referenced) {
+        const daysSince = (Date.now() - new Date(entry.last_referenced).getTime()) / 86400000;
+        if (daysSince < 30)
+            score += 0.1 * (1 - daysSince / 30);
+    }
+    // Penalty for zero references
+    if (entry.times_referenced === 0)
+        score *= 0.9;
+    return score;
+}
+// ── Constants ─────────────────────────────────────────────────────────────────
+const MAX_SHADOW_CHARS = 8000;
+const MAX_SHADOW_ITEMS = 5;
+const MIN_SHADOW_SCORE = 0.35;
+const DECAY_RATE = 0.10;
+const DECAY_THRESHOLD_DAYS = 30;
+// ── Main Class ────────────────────────────────────────────────────────────────
+/**
+ * MindForge Knowledge Graph client (RAG 2.0).
+ */
+class MindForgeMemory {
+    constructor(projectRoot = process.cwd()) {
+        this.projectRoot = projectRoot;
+        this.memoryDir = path.join(projectRoot, '.mindforge', 'memory');
+        this.kbPath = path.join(this.memoryDir, 'knowledge-base.jsonl');
+        this.globalPath = path.join(os.homedir(), '.mindforge', 'global-knowledge-base.jsonl');
+        this.edgesPath = path.join(this.memoryDir, 'graph-edges.jsonl');
+    }
+    // ── Knowledge Store Operations ───────────────────────────────────────────
+    /** Add a new knowledge entry. */
+    async remember(entry) {
+        if (!entry.type)
+            throw new Error('Knowledge entry requires a "type" field');
+        if (!entry.topic)
+            throw new Error('Knowledge entry requires a "topic" field');
+        if (!entry.content)
+            throw new Error('Knowledge entry requires a "content" field');
+        const id = entry.id || generateId();
+        const now = new Date().toISOString();
+        const full = {
+            id,
+            timestamp: now,
+            type: entry.type,
+            topic: (entry.topic || '').slice(0, 80),
+            content: entry.content,
+            source: entry.source || 'sdk',
+            project: entry.project || path.basename(this.projectRoot),
+            confidence: Math.min(1.0, Math.max(0.0, entry.confidence ?? 0.7)),
+            tags: Array.isArray(entry.tags) ? entry.tags : [],
+            linked_adrs: Array.isArray(entry.linked_adrs) ? entry.linked_adrs : [],
+            times_referenced: entry.times_referenced || 0,
+            last_referenced: entry.last_referenced || null,
+            deprecated: false,
+            deprecated_by: null,
+            ...(entry.decision && { decision: entry.decision }),
+            ...(entry.rationale && { rationale: entry.rationale }),
+            ...(entry.root_cause && { root_cause: entry.root_cause }),
+            ...(entry.fix && { fix: entry.fix }),
+            ...(entry.preference && { preference: entry.preference }),
+            ...(entry.strength && { strength: entry.strength }),
+            ...(entry.bug_category && { bug_category: entry.bug_category }),
+            ...(entry.domain && { domain: entry.domain }),
+            ...(entry.tech_stack && { tech_stack: entry.tech_stack }),
+        };
+        appendJsonl(this.kbPath, full);
+        return id;
+    }
+    /** Query the knowledge base. */
+    async query(params = {}) {
+        const { tags = [], topic = '', type, minConfidence = 0.3, limit = 20, includeGlobal = false, includeDeprecated = false, project, } = params;
+        let entries = this.readAllEntries(includeGlobal);
+        if (!includeDeprecated)
+            entries = entries.filter(e => !e.deprecated);
+        if (type)
+            entries = entries.filter(e => e.type === type);
+        if (project)
+            entries = entries.filter(e => !e.project || e.project === project);
+        entries = entries.filter(e => e.confidence >= minConfidence);
+        const scored = entries.map(e => ({
+            entry: e,
+            score: scoreRelevance(e, tags, topic),
+        }));
+        return scored
+            .filter(s => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map(s => s.entry);
+    }
+    /** Reinforce an entry (increase confidence). */
+    async reinforce(id) {
+        const entries = this.readAllEntries(false);
+        const entry = entries.find(e => e.id === id && !e.deprecated);
+        if (!entry)
+            return;
+        const reinforced = {
+            ...entry,
+            confidence: Math.min(1.0, entry.confidence + 0.05),
+            times_referenced: entry.times_referenced + 1,
+            last_referenced: new Date().toISOString(),
+        };
+        appendJsonl(this.kbPath, reinforced);
+    }
+    /** Deprecate an entry. */
+    async deprecate(id, reason, supersededBy) {
+        const entries = this.readAllEntries(false);
+        const entry = entries.find(e => e.id === id);
+        if (!entry)
+            throw new Error(`Knowledge entry not found: ${id}`);
+        const deprecated = {
+            ...entry,
+            deprecated: true,
+            deprecated_by: supersededBy || null,
+        };
+        appendJsonl(this.kbPath, deprecated);
+    }
+    /** Get memory statistics. */
+    async getStats() {
+        const all = this.readAllEntries(false);
+        const active = all.filter(e => !e.deprecated);
+        const byType = {};
+        for (const e of active) {
+            byType[e.type] = (byType[e.type] || 0) + 1;
+        }
+        return {
+            total_entries: all.length,
+            active_entries: active.length,
+            deprecated_entries: all.length - active.length,
+            by_type: byType,
+            avg_confidence: active.length
+                ? active.reduce((s, e) => s + e.confidence, 0) / active.length
+                : 0,
+        };
+    }
+    /** Load context for a session. */
+    async loadContext(opts) {
+        const { techStack = [], phase = '', topic = '' } = opts;
+        const entries = this.readAllEntries(true).filter(e => !e.deprecated && e.confidence >= 0.3);
+        const preferences = entries.filter(e => e.type === 'team_preference');
+        const decisions = entries.filter(e => e.type === 'architectural_decision');
+        const bugPatterns = entries.filter(e => e.type === 'bug_pattern');
+        const codePatterns = entries.filter(e => e.type === 'code_pattern');
+        const domain = entries.filter(e => e.type === 'domain_knowledge');
+        // Apply relevance filtering if topic or techStack given
+        const filterByRelevance = (list) => {
+            if (!topic && techStack.length === 0)
+                return list.slice(0, 5);
+            return list
+                .map(e => ({ entry: e, score: scoreRelevance(e, techStack, topic || phase) }))
+                .sort((a, b) => b.score - a.score)
+                .slice(0, 5)
+                .map(s => s.entry);
+        };
+        const result = {
+            preferences: filterByRelevance(preferences),
+            decisions: filterByRelevance(decisions),
+            bugPatterns: filterByRelevance(bugPatterns),
+            codePatterns: filterByRelevance(codePatterns),
+            domain: filterByRelevance(domain),
+        };
+        const allLoaded = [
+            ...result.preferences,
+            ...result.decisions,
+            ...result.bugPatterns,
+            ...result.codePatterns,
+            ...result.domain,
+        ];
+        const formatted = this.formatSessionContext(result);
+        return {
+            ...result,
+            count: allLoaded.length,
+            formatted,
+        };
+    }
+    // ── Knowledge Graph Operations (RAG 2.0) ──────────────────────────────
+    /** Add a typed edge between two knowledge nodes. */
+    async addEdge(edge) {
+        const id = generateId();
+        const now = new Date().toISOString();
+        const edgeData = {
+            id,
+            sourceId: edge.sourceId,
+            targetId: edge.targetId,
+            type: edge.type,
+            weight: edge.weight ?? 1.0,
+            reason: edge.reason || '',
+            metadata: {},
+            created_at: now,
+            last_traversed: null,
+            traversal_count: 0,
+            deprecated: false,
+        };
+        const checksum = computeChecksum(edgeData);
+        const fullEdge = { ...edgeData, checksum };
+        appendJsonl(this.edgesPath, fullEdge);
+        return id;
+    }
+    /** Get all edges for a specific node. */
+    async getEdges(nodeId, opts) {
+        const edges = this.readAllEdges();
+        const direction = opts?.direction || 'both';
+        const edgeTypes = opts?.edgeTypes;
+        let filtered = edges.filter(e => !e.deprecated);
+        if (direction === 'outgoing') {
+            filtered = filtered.filter(e => e.sourceId === nodeId);
+        }
+        else if (direction === 'incoming') {
+            filtered = filtered.filter(e => e.targetId === nodeId);
+        }
+        else {
+            filtered = filtered.filter(e => e.sourceId === nodeId || e.targetId === nodeId);
+        }
+        if (edgeTypes && edgeTypes.length > 0) {
+            filtered = filtered.filter(e => edgeTypes.includes(e.type));
+        }
+        return filtered;
+    }
+    /** BFS traversal from a starting node. */
+    async traverse(startId, maxDepth, opts) {
+        const edges = this.readAllEdges().filter(e => !e.deprecated);
+        const depth = maxDepth ?? 3;
+        const edgeTypes = opts?.edgeTypes;
+        const minWeight = opts?.minWeight ?? 0;
+        // Build adjacency map
+        const adjacency = new Map();
+        for (const edge of edges) {
+            if (edgeTypes && !edgeTypes.includes(edge.type))
+                continue;
+            if (edge.weight < minWeight)
+                continue;
+            if (!adjacency.has(edge.sourceId))
+                adjacency.set(edge.sourceId, []);
+            adjacency.get(edge.sourceId).push({ target: edge.targetId, edge });
+            // For undirected traversal of RELATED_TO edges
+            if (edge.type === 'RELATED_TO') {
+                if (!adjacency.has(edge.targetId))
+                    adjacency.set(edge.targetId, []);
+                adjacency.get(edge.targetId).push({ target: edge.sourceId, edge });
+            }
+        }
+        // BFS
+        const results = [];
+        const visited = new Set([startId]);
+        const queue = [
+            { id: startId, depth: 0, path: [startId] },
+        ];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current.depth > 0) {
+                results.push({
+                    id: current.id,
+                    depth: current.depth,
+                    path: current.path,
+                });
+            }
+            if (current.depth >= depth)
+                continue;
+            const neighbors = adjacency.get(current.id) || [];
+            for (const { target } of neighbors) {
+                if (!visited.has(target)) {
+                    visited.add(target);
+                    queue.push({
+                        id: target,
+                        depth: current.depth + 1,
+                        path: [...current.path, target],
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    /** Find related knowledge via keyword-based scoring + graph traversal. */
+    async findRelated(queryText, opts) {
+        const maxHops = opts?.maxHops ?? 2;
+        const topK = opts?.topK ?? 10;
+        const entries = this.readAllEntries(true).filter(e => !e.deprecated && e.confidence >= 0.3);
+        // Keyword-based scoring (TF-IDF approximation)
+        const queryWords = queryText
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(w => w.length > 3);
+        const scored = entries.map(entry => {
+            const text = `${entry.topic} ${entry.content} ${(entry.tags || []).join(' ')}`.toLowerCase();
+            const matches = queryWords.filter(w => text.includes(w)).length;
+            const score = matches / Math.max(queryWords.length, 1);
+            return { id: entry.id, score, source: entry.source };
+        });
+        // Get top seed results
+        const seeds = scored
+            .filter(s => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 5);
+        // Expand via graph traversal
+        const expanded = new Map();
+        for (const seed of seeds) {
+            expanded.set(seed.id, { score: seed.score, source: seed.source });
+        }
+        if (maxHops > 0 && seeds.length > 0) {
+            for (const seed of seeds) {
+                const traversed = await this.traverse(seed.id, maxHops);
+                for (const node of traversed) {
+                    const existing = expanded.get(node.id);
+                    const decayedScore = seed.score * Math.pow(0.5, node.depth);
+                    if (!existing || existing.score < decayedScore) {
+                        const entry = entries.find(e => e.id === node.id);
+                        expanded.set(node.id, {
+                            score: decayedScore,
+                            source: entry?.source || 'graph',
+                        });
+                    }
+                }
+            }
+        }
+        return [...expanded.entries()]
+            .map(([id, data]) => ({ id, ...data }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+    /** Generate auto-shadow context for a task. */
+    async autoShadow(opts) {
+        const { taskDescription, excludeIds = [], techStack = [] } = opts;
+        if (!taskDescription || taskDescription.length < 10) {
+            return { formatted: '', items: [], count: 0, budgetUsed: 0 };
+        }
+        const entries = this.readAllEntries(true).filter(e => !e.deprecated && e.confidence >= 0.3 && !excludeIds.includes(e.id));
+        // Score entries against task description
+        const queryWords = taskDescription
+            .toLowerCase()
+            .split(/\s+/)
+            .filter(w => w.length > 3);
+        const scored = entries
+            .map(entry => {
+            const text = `${entry.topic} ${entry.content} ${(entry.tags || []).join(' ')}`.toLowerCase();
+            let score = 0;
+            // Keyword matching
+            const matches = queryWords.filter(w => text.includes(w)).length;
+            score += (matches / Math.max(queryWords.length, 1)) * 0.6;
+            // Tech stack boost
+            if (techStack.length > 0 && entry.tech_stack) {
+                const stackOverlap = techStack.filter(t => entry.tech_stack.some(et => et.toLowerCase() === t.toLowerCase())).length;
+                score += (stackOverlap / techStack.length) * 0.2;
+            }
+            // Confidence factor
+            score += entry.confidence * 0.2;
+            return {
+                id: entry.id,
+                type: entry.type,
+                topic: entry.topic,
+                content: entry.content,
+                confidence: entry.confidence,
+                score,
+                source: entry.source,
+                tags: entry.tags,
+            };
+        })
+            .filter(item => item.score >= MIN_SHADOW_SCORE)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, MAX_SHADOW_ITEMS);
+        // Format within budget
+        let budgetUsed = 0;
+        const items = [];
+        const lines = ['### Auto-Shadow Context'];
+        for (const item of scored) {
+            const line = `- [${item.type}] ${item.topic}: ${item.content.slice(0, 150)}`;
+            if (budgetUsed + line.length > MAX_SHADOW_CHARS)
+                break;
+            lines.push(line);
+            items.push(item);
+            budgetUsed += line.length;
+        }
+        return {
+            formatted: items.length > 0 ? lines.join('\n') : '',
+            items,
+            count: items.length,
+            budgetUsed,
+        };
+    }
+    /** Get graph statistics. */
+    async getGraphStats() {
+        const edges = this.readAllEdges().filter(e => !e.deprecated);
+        const entries = this.readAllEntries(false);
+        const nodeIds = new Set(entries.map(e => e.id));
+        const connectedNodes = new Set();
+        const edgesByType = {};
+        let totalWeight = 0;
+        for (const edge of edges) {
+            connectedNodes.add(edge.sourceId);
+            connectedNodes.add(edge.targetId);
+            edgesByType[edge.type] = (edgesByType[edge.type] || 0) + 1;
+            totalWeight += edge.weight;
+        }
+        return {
+            total_nodes: nodeIds.size,
+            total_edges: edges.length,
+            edges_by_type: edgesByType,
+            orphan_nodes: nodeIds.size - connectedNodes.size,
+            avg_weight: edges.length > 0 ? totalWeight / edges.length : 0,
+            connected_ratio: nodeIds.size > 0 ? connectedNodes.size / nodeIds.size : 0,
+        };
+    }
+    /** Apply weight decay to stale edges. */
+    async decayEdges() {
+        const edges = this.readAllEdges();
+        const now = Date.now();
+        let decayed = 0;
+        let pruned = 0;
+        for (const edge of edges) {
+            if (edge.deprecated)
+                continue;
+            const lastActivity = edge.last_traversed || edge.created_at;
+            const daysSince = (now - new Date(lastActivity).getTime()) / 86400000;
+            if (daysSince > DECAY_THRESHOLD_DAYS) {
+                const newWeight = edge.weight * (1 - DECAY_RATE);
+                if (newWeight < 0.1) {
+                    // Prune by deprecating
+                    const prunedEdge = { ...edge, deprecated: true };
+                    appendJsonl(this.edgesPath, prunedEdge);
+                    pruned++;
+                }
+                else {
+                    const decayedEdge = { ...edge, weight: newWeight };
+                    appendJsonl(this.edgesPath, decayedEdge);
+                    decayed++;
+                }
+            }
+        }
+        return { decayed, pruned };
+    }
+    /** Detect cycles in directed edge types. */
+    async detectCycles() {
+        const edges = this.readAllEdges().filter(e => !e.deprecated && e.type !== 'RELATED_TO');
+        // Build directed adjacency
+        const adjacency = new Map();
+        const allNodes = new Set();
+        for (const edge of edges) {
+            allNodes.add(edge.sourceId);
+            allNodes.add(edge.targetId);
+            if (!adjacency.has(edge.sourceId))
+                adjacency.set(edge.sourceId, []);
+            adjacency.get(edge.sourceId).push(edge.targetId);
+        }
+        // DFS-based cycle detection
+        const cycles = [];
+        const visited = new Set();
+        const inStack = new Set();
+        const dfs = (node, pathArr) => {
+            visited.add(node);
+            inStack.add(node);
+            const neighbors = adjacency.get(node) || [];
+            for (const neighbor of neighbors) {
+                if (inStack.has(neighbor)) {
+                    // Found a cycle
+                    const cycleStart = pathArr.indexOf(neighbor);
+                    if (cycleStart >= 0) {
+                        cycles.push([...pathArr.slice(cycleStart), neighbor]);
+                    }
+                }
+                else if (!visited.has(neighbor)) {
+                    dfs(neighbor, [...pathArr, neighbor]);
+                }
+            }
+            inStack.delete(node);
+        };
+        for (const node of allNodes) {
+            if (!visited.has(node)) {
+                dfs(node, [node]);
+            }
+        }
+        return cycles;
+    }
+    /** Verify SHA-256 integrity of all edges. */
+    async verifyIntegrity() {
+        const edges = this.readAllEdges();
+        let valid = 0;
+        const corrupted = [];
+        for (const edge of edges) {
+            const { checksum, ...rest } = edge;
+            const expected = computeChecksum(rest);
+            if (expected === checksum) {
+                valid++;
+            }
+            else {
+                corrupted.push(edge.id);
+            }
+        }
+        return { valid, corrupted };
+    }
+    // ── Private Helpers ─────────────────────────────────────────────────────
+    readAllEntries(includeGlobal) {
+        let entries = readJsonlFile(this.kbPath);
+        if (includeGlobal && fs.existsSync(this.globalPath)) {
+            const globalEntries = readJsonlFile(this.globalPath).map(e => ({ ...e, global: true }));
+            entries = [...entries, ...globalEntries];
+        }
+        return entries;
+    }
+    readAllEdges() {
+        return readJsonlFile(this.edgesPath);
+    }
+    formatSessionContext(ctx) {
+        const sections = [];
+        if (ctx.preferences.length > 0) {
+            sections.push('### Team Preferences');
+            for (const e of ctx.preferences) {
+                sections.push(`- [${(e.confidence * 100).toFixed(0)}% confidence] ${e.topic}: ${e.content.slice(0, 200)}`);
+            }
+        }
+        if (ctx.decisions.length > 0) {
+            sections.push('\n### Architectural Decisions');
+            for (const e of ctx.decisions) {
+                sections.push(`- ${e.topic}: ${e.content.slice(0, 200)}`);
+            }
+        }
+        if (ctx.bugPatterns.length > 0) {
+            sections.push('\n### Known Bug Patterns');
+            for (const e of ctx.bugPatterns) {
+                sections.push(`- ${e.topic}: ${e.content.slice(0, 200)}`);
+            }
+        }
+        if (ctx.codePatterns.length > 0) {
+            sections.push('\n### Code Patterns');
+            for (const e of ctx.codePatterns) {
+                sections.push(`- ${e.topic}: ${e.content.slice(0, 200)}`);
+            }
+        }
+        if (ctx.domain.length > 0) {
+            sections.push('\n### Domain Knowledge');
+            for (const e of ctx.domain) {
+                sections.push(`- ${e.topic}: ${e.content.slice(0, 200)}`);
+            }
+        }
+        return sections.join('\n');
+    }
+}
+exports.MindForgeMemory = MindForgeMemory;