@launchapp-dev/ao-memory-mcp 2.0.0 → 2.0.1

package/dist/tools/recall.js

@@ -0,0 +1,180 @@
+import { jsonResult, errorResult, touchAccess } from "../db.js";
+import { embed, hybridSearch } from "../embeddings.js";
+export const recallTools = [
+    {
+        name: "memory.recall",
+        description: "Recall memories with structured filters. Supports filtering by type, scope, namespace, agent role, tags, date range. Returns entries sorted by date.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                memory_type: { type: "string", enum: ["semantic", "episodic", "procedural"], description: "Filter by type" },
+                scope: { type: "string", description: "Filter by scope" },
+                namespace: { type: "string", description: "Filter by namespace (project name, etc.)" },
+                agent_role: { type: "string", description: "Filter by agent role" },
+                task_id: { type: "string", description: "Filter by task ID" },
+                status: { type: "string", enum: ["active", "summarized", "archived"], description: "Default: active" },
+                date_from: { type: "string", description: "From ISO date" },
+                date_to: { type: "string", description: "To ISO date" },
+                tags: { type: "array", items: { type: "string" }, description: "Must have ALL specified tags" },
+                limit: { type: "number", description: "Max results (default 50)" },
+                offset: { type: "number", description: "Pagination offset" },
+                order: { type: "string", enum: ["newest", "oldest", "most_accessed", "highest_confidence"], description: "Sort order" },
+            },
+        },
+    },
+    {
+        name: "memory.search",
+        description: "Hybrid semantic + keyword search across all memories. Uses vector similarity and FTS5 together for best results.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Natural language search query" },
+                memory_type: { type: "string", description: "Restrict to type" },
+                namespace: { type: "string", description: "Restrict to namespace" },
+                agent_role: { type: "string", description: "Restrict to agent role" },
+                status: { type: "string", description: "Restrict to status" },
+                limit: { type: "number", description: "Max results (default 10)" },
+                alpha: { type: "number", description: "Semantic vs keyword weight: 0=all keyword, 1=all semantic (default 0.5)" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "memory.get",
+        description: "Get a single memory by ID. Updates access tracking.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Memory ID" },
+            },
+            required: ["id"],
+        },
+    },
+];
+export function handleRecall(db, name, args) {
+    if (name === "memory.recall")
+        return memoryRecall(db, args);
+    if (name === "memory.search")
+        return memorySearch(db, args);
+    if (name === "memory.get")
+        return memoryGet(db, args);
+    return null;
+}
+function memoryRecall(db, args) {
+    const conditions = [];
+    const vals = [];
+    conditions.push("status = ?");
+    vals.push(args.status || "active");
+    if (args.memory_type) {
+        conditions.push("memory_type = ?");
+        vals.push(args.memory_type);
+    }
+    if (args.scope) {
+        conditions.push("scope = ?");
+        vals.push(args.scope);
+    }
+    if (args.namespace) {
+        conditions.push("namespace = ?");
+        vals.push(args.namespace);
+    }
+    if (args.agent_role) {
+        conditions.push("agent_role = ?");
+        vals.push(args.agent_role);
+    }
+    if (args.task_id) {
+        conditions.push("task_id = ?");
+        vals.push(args.task_id);
+    }
+    if (args.date_from) {
+        conditions.push("occurred_at >= ?");
+        vals.push(args.date_from);
+    }
+    if (args.date_to) {
+        conditions.push("occurred_at <= ?");
+        vals.push(args.date_to);
+    }
+    if (args.tags?.length) {
+        for (const tag of args.tags) {
+            conditions.push("EXISTS (SELECT 1 FROM json_each(tags) WHERE json_each.value = ?)");
+            vals.push(tag);
+        }
+    }
+    const orderMap = {
+        newest: "occurred_at DESC",
+        oldest: "occurred_at ASC",
+        most_accessed: "access_count DESC",
+        highest_confidence: "confidence DESC",
+    };
+    const order = orderMap[args.order || "newest"] || "occurred_at DESC";
+    const limit = args.limit || 50;
+    const offset = args.offset || 0;
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const rows = db.prepare(`SELECT * FROM memories ${where} ORDER BY ${order} LIMIT ? OFFSET ?`).all(...vals, limit, offset);
+    return jsonResult({ memories: rows, count: rows.length });
+}
+async function memorySearch(db, args) {
+    const limit = args.limit || 10;
+    const alpha = args.alpha ?? 0.5;
+    // Get embedding for query
+    let queryEmbedding;
+    try {
+        queryEmbedding = await embed(args.query, true);
+    }
+    catch {
+        // Fallback to FTS-only
+        return ftsOnlySearch(db, args);
+    }
+    const results = hybridSearch(db, "memories_fts", "vec_memories", args.query, queryEmbedding, limit * 3, alpha);
+    if (results.length === 0)
+        return jsonResult({ memories: [], count: 0 });
+    // Fetch full rows and apply filters
+    const ids = results.map(r => r.rowid);
+    const scoreMap = new Map(results.map(r => [r.rowid, r.score]));
+    const conditions = [`id IN (${ids.map(() => "?").join(",")})`];
+    const vals = [...ids];
+    if (args.memory_type) {
+        conditions.push("memory_type = ?");
+        vals.push(args.memory_type);
+    }
+    if (args.namespace) {
+        conditions.push("namespace = ?");
+        vals.push(args.namespace);
+    }
+    if (args.agent_role) {
+        conditions.push("agent_role = ?");
+        vals.push(args.agent_role);
+    }
+    if (args.status) {
+        conditions.push("status = ?");
+        vals.push(args.status);
+    }
+    const rows = db.prepare(`SELECT * FROM memories WHERE ${conditions.join(" AND ")}`).all(...vals);
+    // Sort by hybrid score and limit
+    const scored = rows
+        .map(r => ({ ...r, _score: scoreMap.get(r.id) || 0 }))
+        .sort((a, b) => b._score - a._score)
+        .slice(0, limit);
+    // Touch access for returned results
+    for (const row of scored)
+        touchAccess(db, row.id);
+    return jsonResult({ memories: scored, count: scored.length });
+}
+function ftsOnlySearch(db, args) {
+    const limit = args.limit || 10;
+    const rows = db.prepare(`
+    SELECT m.*, snippet(memories_fts, 0, '<mark>', '</mark>', '...', 32) as title_snippet,
+           snippet(memories_fts, 1, '<mark>', '</mark>', '...', 64) as content_snippet
+    FROM memories_fts f
+    JOIN memories m ON m.id = f.rowid
+    WHERE memories_fts MATCH ?
+    ORDER BY rank LIMIT ?
+  `).all(args.query, limit);
+    return jsonResult({ memories: rows, count: rows.length, mode: "keyword_only" });
+}
+function memoryGet(db, args) {
+    const entry = db.prepare("SELECT * FROM memories WHERE id = ?").get(args.id);
+    if (!entry)
+        return errorResult(`Memory ${args.id} not found`);
+    touchAccess(db, args.id);
+    return jsonResult(entry);
+}

package/dist/tools/stats.d.ts

@@ -0,0 +1,24 @@
+import type Database from "better-sqlite3";
+export declare const statsTools: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            namespace: {
+                type: string;
+                description: string;
+            };
+            agent_role: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+}[];
+export declare function handleStats(db: Database.Database, name: string, args: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/tools/stats.js

@@ -0,0 +1,50 @@
+import { jsonResult } from "../db.js";
+export const statsTools = [
+    {
+        name: "memory.stats",
+        description: "Get aggregate statistics across all memory types.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                namespace: { type: "string", description: "Filter by namespace" },
+                agent_role: { type: "string", description: "Filter by agent role" },
+            },
+        },
+    },
+];
+export function handleStats(db, name, args) {
+    if (name === "memory.stats")
+        return memoryStats(db, args);
+    return null;
+}
+function memoryStats(db, args) {
+    const conditions = [];
+    const vals = [];
+    if (args.namespace) {
+        conditions.push("namespace = ?");
+        vals.push(args.namespace);
+    }
+    if (args.agent_role) {
+        conditions.push("agent_role = ?");
+        vals.push(args.agent_role);
+    }
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const totalMemories = db.prepare(`SELECT COUNT(*) as c FROM memories ${where}`).get(...vals).c;
+    const byType = db.prepare(`SELECT memory_type, COUNT(*) as count FROM memories ${where} GROUP BY memory_type`).all(...vals);
+    const byStatus = db.prepare(`SELECT status, COUNT(*) as count FROM memories ${where} GROUP BY status`).all(...vals);
+    const byScope = db.prepare(`SELECT scope, COUNT(*) as count FROM memories ${where} GROUP BY scope`).all(...vals);
+    const byRole = db.prepare(`SELECT agent_role, COUNT(*) as count FROM memories ${where} GROUP BY agent_role`).all(...vals);
+    const byNamespace = db.prepare(`SELECT namespace, COUNT(*) as count FROM memories ${where} GROUP BY namespace ORDER BY count DESC LIMIT 20`).all(...vals);
+    const dateRange = db.prepare(`SELECT MIN(occurred_at) as oldest, MAX(occurred_at) as newest FROM memories ${where}`).get(...vals);
+    const totalDocs = db.prepare("SELECT COUNT(*) as c FROM documents").get().c;
+    const totalChunks = db.prepare("SELECT COUNT(*) as c FROM chunks").get().c;
+    const totalEntities = db.prepare("SELECT COUNT(*) as c FROM entities").get().c;
+    const totalRelations = db.prepare("SELECT COUNT(*) as c FROM relations").get().c;
+    const totalEpisodes = db.prepare("SELECT COUNT(*) as c FROM episodes").get().c;
+    return jsonResult({
+        memories: { total: totalMemories, by_type: byType, by_status: byStatus, by_scope: byScope, by_role: byRole, by_namespace: byNamespace, oldest: dateRange?.oldest, newest: dateRange?.newest },
+        documents: { total: totalDocs, total_chunks: totalChunks },
+        knowledge_graph: { entities: totalEntities, relations: totalRelations },
+        episodes: { total: totalEpisodes },
+    });
+}

package/dist/tools/store.d.ts

@@ -0,0 +1,180 @@
+import type Database from "better-sqlite3";
+export declare const storeTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            memory_type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            scope: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+            };
+            agent_role: {
+                type: string;
+                description: string;
+            };
+            task_id: {
+                type: string;
+                description: string;
+            };
+            pr_number: {
+                type: string;
+                description: string;
+            };
+            run_id: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            metadata: {
+                type: string;
+                description: string;
+            };
+            confidence: {
+                type: string;
+                description: string;
+            };
+            occurred_at: {
+                type: string;
+                description: string;
+            };
+            id?: undefined;
+            status?: undefined;
+            superseded_by?: undefined;
+            ids?: undefined;
+            before?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description?: undefined;
+            };
+            content: {
+                type: string;
+                description?: undefined;
+            };
+            status: {
+                type: string;
+                enum: string[];
+            };
+            confidence: {
+                type: string;
+                description?: undefined;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description?: undefined;
+            };
+            metadata: {
+                type: string;
+                description?: undefined;
+            };
+            superseded_by: {
+                type: string;
+                description: string;
+            };
+            memory_type?: undefined;
+            scope?: undefined;
+            namespace?: undefined;
+            agent_role?: undefined;
+            task_id?: undefined;
+            pr_number?: undefined;
+            run_id?: undefined;
+            occurred_at?: undefined;
+            ids?: undefined;
+            before?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            agent_role: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+            };
+            before: {
+                type: string;
+                description: string;
+            };
+            memory_type?: undefined;
+            title?: undefined;
+            content?: undefined;
+            scope?: undefined;
+            task_id?: undefined;
+            pr_number?: undefined;
+            run_id?: undefined;
+            tags?: undefined;
+            metadata?: undefined;
+            confidence?: undefined;
+            occurred_at?: undefined;
+            id?: undefined;
+            status?: undefined;
+            superseded_by?: undefined;
+        };
+        required?: undefined;
+    };
+})[];
+export declare function handleStore(db: Database.Database, name: string, args: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/store.js

@@ -0,0 +1,176 @@
+import { contentHash, now, jsonResult, errorResult, touchAccess } from "../db.js";
+import { embed, storeVector } from "../embeddings.js";
+export const storeTools = [
+    {
+        name: "memory.remember",
+        description: "Store a new memory. Automatically embeds for semantic search. Deduplicates via content hash. Supports semantic (facts/knowledge), episodic (events/history), and procedural (how-to/workflows) types.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                memory_type: { type: "string", enum: ["semantic", "episodic", "procedural"], description: "Type: semantic (facts), episodic (events), procedural (how-to)" },
+                title: { type: "string", description: "Short summary" },
+                content: { type: "string", description: "Full content (markdown)" },
+                scope: { type: "string", enum: ["global", "user", "project", "session"], description: "Scope (default: project)" },
+                namespace: { type: "string", description: "Scope identifier — project name, user id, session id" },
+                agent_role: { type: "string", description: "Agent role storing this memory" },
+                task_id: { type: "string", description: "Task ID reference" },
+                pr_number: { type: "number", description: "PR number" },
+                run_id: { type: "string", description: "Run identifier" },
+                tags: { type: "array", items: { type: "string" }, description: "Tags" },
+                metadata: { type: "object", description: "Custom metadata" },
+                confidence: { type: "number", description: "Confidence score 0.0-1.0 (default 1.0)" },
+                occurred_at: { type: "string", description: "ISO 8601 date (default: now)" },
+            },
+            required: ["memory_type", "title", "content"],
+        },
+    },
+    {
+        name: "memory.update",
+        description: "Update an existing memory by ID.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Memory ID" },
+                title: { type: "string" },
+                content: { type: "string" },
+                status: { type: "string", enum: ["active", "summarized", "archived"] },
+                confidence: { type: "number" },
+                tags: { type: "array", items: { type: "string" } },
+                metadata: { type: "object" },
+                superseded_by: { type: "number", description: "ID of memory that replaces this one" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "memory.forget",
+        description: "Archive memories. Soft delete — they remain queryable with status filter.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ids: { type: "array", items: { type: "number" }, description: "Specific IDs to archive" },
+                agent_role: { type: "string", description: "Archive all for this role" },
+                namespace: { type: "string", description: "Archive all in this namespace" },
+                before: { type: "string", description: "Archive entries before this ISO date" },
+            },
+        },
+    },
+];
+export function handleStore(db, name, args) {
+    if (name === "memory.remember")
+        return memoryRemember(db, args);
+    if (name === "memory.update")
+        return memoryUpdate(db, args);
+    if (name === "memory.forget")
+        return memoryForget(db, args);
+    return null;
+}
+async function memoryRemember(db, args) {
+    const { memory_type, title, content } = args;
+    const scope = args.scope || "project";
+    const hash = contentHash(memory_type, scope, args.namespace || "", title, content);
+    const existing = db.prepare("SELECT id FROM memories WHERE content_hash = ?").get(hash);
+    if (existing) {
+        touchAccess(db, existing.id);
+        return jsonResult({ duplicate: true, existing_id: existing.id });
+    }
+    const ts = now();
+    const result = db.prepare(`
+    INSERT INTO memories (memory_type, scope, namespace, agent_role, title, content, task_id, pr_number, run_id, status, confidence, tags, metadata, created_at, occurred_at, updated_at, content_hash)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?)
+  `).run(memory_type, scope, args.namespace || null, args.agent_role || null, title, content, args.task_id || null, args.pr_number || null, args.run_id || null, args.confidence ?? 1.0, JSON.stringify(args.tags || []), JSON.stringify(args.metadata || {}), ts, args.occurred_at || ts, ts, hash);
+    const id = Number(result.lastInsertRowid);
+    // Embed asynchronously
+    try {
+        const embedding = await embed(`${title}\n${content}`);
+        storeVector(db, "vec_memories", id, embedding);
+    }
+    catch (e) {
+        console.error(`[ao-memory] Embedding failed for memory ${id}:`, e);
+    }
+    return jsonResult({ id, created: true });
+}
+async function memoryUpdate(db, args) {
+    const { id, ...updates } = args;
+    const entry = db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
+    if (!entry)
+        return errorResult(`Memory ${id} not found`);
+    const sets = [];
+    const vals = [];
+    if (updates.title !== undefined) {
+        sets.push("title = ?");
+        vals.push(updates.title);
+    }
+    if (updates.content !== undefined) {
+        sets.push("content = ?");
+        vals.push(updates.content);
+    }
+    if (updates.status !== undefined) {
+        sets.push("status = ?");
+        vals.push(updates.status);
+    }
+    if (updates.confidence !== undefined) {
+        sets.push("confidence = ?");
+        vals.push(updates.confidence);
+    }
+    if (updates.superseded_by !== undefined) {
+        sets.push("superseded_by = ?");
+        vals.push(updates.superseded_by);
+    }
+    if (updates.tags !== undefined) {
+        sets.push("tags = ?");
+        vals.push(JSON.stringify(updates.tags));
+    }
+    if (updates.metadata !== undefined) {
+        const merged = { ...JSON.parse(entry.metadata), ...updates.metadata };
+        sets.push("metadata = ?");
+        vals.push(JSON.stringify(merged));
+    }
+    if (sets.length === 0)
+        return errorResult("No fields to update");
+    sets.push("updated_at = ?");
+    vals.push(now());
+    if (updates.title !== undefined || updates.content !== undefined) {
+        const newTitle = updates.title || entry.title;
+        const newContent = updates.content || entry.content;
+        const hash = contentHash(entry.memory_type, entry.scope, entry.namespace || "", newTitle, newContent);
+        sets.push("content_hash = ?");
+        vals.push(hash);
+        // Re-embed
+        try {
+            const embedding = await embed(`${newTitle}\n${newContent}`);
+            storeVector(db, "vec_memories", id, embedding);
+        }
+        catch { }
+    }
+    vals.push(id);
+    db.prepare(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`).run(...vals);
+    return jsonResult({ id, updated: true });
+}
+function memoryForget(db, args) {
+    const { ids, agent_role, namespace, before } = args;
+    if (!ids && !agent_role && !namespace && !before) {
+        return errorResult("At least one filter required");
+    }
+    const conditions = ["status = 'active'"];
+    const vals = [];
+    if (ids?.length) {
+        conditions.push(`id IN (${ids.map(() => "?").join(",")})`);
+        vals.push(...ids);
+    }
+    if (agent_role) {
+        conditions.push("agent_role = ?");
+        vals.push(agent_role);
+    }
+    if (namespace) {
+        conditions.push("namespace = ?");
+        vals.push(namespace);
+    }
+    if (before) {
+        conditions.push("occurred_at < ?");
+        vals.push(before);
+    }
+    const ts = now();
+    const result = db.prepare(`UPDATE memories SET status = 'archived', updated_at = ? WHERE ${conditions.join(" AND ")}`).run(ts, ...vals);
+    return jsonResult({ archived_count: result.changes });
+}

package/dist/tools/summarize.d.ts

@@ -0,0 +1,74 @@
+import type Database from "better-sqlite3";
+export declare const summarizeTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            namespace: {
+                type: string;
+                description: string;
+            };
+            agent_role: {
+                type: string;
+                description: string;
+            };
+            summary_title: {
+                type: string;
+                description: string;
+            };
+            summary_body: {
+                type: string;
+                description: string;
+            };
+            before: {
+                type: string;
+                description: string;
+            };
+            entry_ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            older_than_days?: undefined;
+            min_entries?: undefined;
+            dry_run?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            older_than_days: {
+                type: string;
+                description: string;
+            };
+            min_entries: {
+                type: string;
+                description: string;
+            };
+            dry_run: {
+                type: string;
+                description: string;
+            };
+            namespace?: undefined;
+            agent_role?: undefined;
+            summary_title?: undefined;
+            summary_body?: undefined;
+            before?: undefined;
+            entry_ids?: undefined;
+        };
+        required?: undefined;
+    };
+})[];
+export declare function handleSummarize(db: Database.Database, name: string, args: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};