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

package/dist/tools/documents.d.ts

@@ -0,0 +1,142 @@
+import type Database from "better-sqlite3";
+export declare const documentTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            title: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            source: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+            };
+            mime_type: {
+                type: string;
+                description: string;
+            };
+            chunk_size: {
+                type: string;
+                description: string;
+            };
+            chunk_overlap: {
+                type: string;
+                description: string;
+            };
+            metadata: {
+                type: string;
+                description: string;
+            };
+            query?: undefined;
+            limit?: undefined;
+            alpha?: undefined;
+            id?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            alpha: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            content?: undefined;
+            source?: undefined;
+            mime_type?: undefined;
+            chunk_size?: undefined;
+            chunk_overlap?: undefined;
+            metadata?: undefined;
+            id?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            namespace: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            content?: undefined;
+            source?: undefined;
+            mime_type?: undefined;
+            chunk_size?: undefined;
+            chunk_overlap?: undefined;
+            metadata?: undefined;
+            query?: undefined;
+            alpha?: undefined;
+            id?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            content?: undefined;
+            source?: undefined;
+            namespace?: undefined;
+            mime_type?: undefined;
+            chunk_size?: undefined;
+            chunk_overlap?: undefined;
+            metadata?: undefined;
+            query?: undefined;
+            limit?: undefined;
+            alpha?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleDocuments(db: Database.Database, name: string, args: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/documents.js

@@ -0,0 +1,201 @@
+import { now, jsonResult, errorResult, chunkText } from "../db.js";
+import { embed, storeVector, deleteVector, hybridSearch } from "../embeddings.js";
+export const documentTools = [
+    {
+        name: "memory.doc.ingest",
+        description: "Ingest a document into memory. Automatically chunks and embeds for semantic retrieval. Great for architecture docs, specs, READMEs, code files, or any reference material.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Document title" },
+                content: { type: "string", description: "Full document content" },
+                source: { type: "string", description: "File path, URL, or identifier" },
+                namespace: { type: "string", description: "Project/scope for this document" },
+                mime_type: { type: "string", description: "Content type (default: text/plain)" },
+                chunk_size: { type: "number", description: "Max chars per chunk (default: 1000)" },
+                chunk_overlap: { type: "number", description: "Overlap chars between chunks (default: 100)" },
+                metadata: { type: "object", description: "Custom metadata" },
+            },
+            required: ["title", "content"],
+        },
+    },
+    {
+        name: "memory.doc.search",
+        description: "Search across ingested documents using hybrid semantic + keyword search. Returns relevant chunks with document context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                namespace: { type: "string", description: "Restrict to namespace" },
+                limit: { type: "number", description: "Max chunks to return (default 5)" },
+                alpha: { type: "number", description: "Semantic vs keyword weight (default 0.6)" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "memory.doc.list",
+        description: "List ingested documents.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                namespace: { type: "string", description: "Filter by namespace" },
+                limit: { type: "number", description: "Max results (default 50)" },
+            },
+        },
+    },
+    {
+        name: "memory.doc.get",
+        description: "Get a full document by ID, including all its chunks.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Document ID" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "memory.doc.delete",
+        description: "Delete a document and all its chunks.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "Document ID" },
+            },
+            required: ["id"],
+        },
+    },
+];
+export function handleDocuments(db, name, args) {
+    if (name === "memory.doc.ingest")
+        return docIngest(db, args);
+    if (name === "memory.doc.search")
+        return docSearch(db, args);
+    if (name === "memory.doc.list")
+        return docList(db, args);
+    if (name === "memory.doc.get")
+        return docGet(db, args);
+    if (name === "memory.doc.delete")
+        return docDelete(db, args);
+    return null;
+}
+async function docIngest(db, args) {
+    const ts = now();
+    const chunkSize = args.chunk_size || 1000;
+    const chunkOverlap = args.chunk_overlap || 100;
+    // Check for existing doc with same source
+    if (args.source) {
+        const existing = db.prepare("SELECT id FROM documents WHERE source = ? AND namespace IS ?").get(args.source, args.namespace || null);
+        if (existing) {
+            // Re-ingest: delete old chunks
+            const oldChunks = db.prepare("SELECT id FROM chunks WHERE document_id = ?").all(existing.id);
+            for (const c of oldChunks)
+                deleteVector(db, "vec_chunks", c.id);
+            db.prepare("DELETE FROM chunks WHERE document_id = ?").run(existing.id);
+            db.prepare("DELETE FROM documents WHERE id = ?").run(existing.id);
+        }
+    }
+    const docResult = db.prepare(`
+    INSERT INTO documents (namespace, title, source, mime_type, content, metadata, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(args.namespace || null, args.title, args.source || null, args.mime_type || "text/plain", args.content, JSON.stringify(args.metadata || {}), ts, ts);
+    const docId = Number(docResult.lastInsertRowid);
+    const textChunks = chunkText(args.content, chunkSize, chunkOverlap);
+    const insertChunk = db.prepare(`
+    INSERT INTO chunks (document_id, chunk_index, content, char_offset, char_length, metadata, created_at)
+    VALUES (?, ?, ?, ?, ?, '{}', ?)
+  `);
+    const chunkIds = [];
+    for (let i = 0; i < textChunks.length; i++) {
+        const c = textChunks[i];
+        const result = insertChunk.run(docId, i, c.content, c.offset, c.content.length, ts);
+        chunkIds.push(Number(result.lastInsertRowid));
+    }
+    // Embed all chunks
+    let embedded = 0;
+    for (let i = 0; i < textChunks.length; i++) {
+        try {
+            const embedding = await embed(textChunks[i].content);
+            storeVector(db, "vec_chunks", chunkIds[i], embedding);
+            embedded++;
+        }
+        catch (e) {
+            console.error(`[ao-memory] Chunk embed failed:`, e);
+        }
+    }
+    return jsonResult({ document_id: docId, chunks: textChunks.length, embedded });
+}
+async function docSearch(db, args) {
+    const limit = args.limit || 5;
+    const alpha = args.alpha ?? 0.6;
+    let queryEmbedding;
+    try {
+        queryEmbedding = await embed(args.query, true);
+    }
+    catch {
+        // FTS-only fallback
+        const rows = db.prepare(`
+      SELECT c.*, d.title as doc_title, d.source as doc_source
+      FROM chunks_fts f
+      JOIN chunks c ON c.id = f.rowid
+      JOIN documents d ON d.id = c.document_id
+      ${args.namespace ? "WHERE d.namespace = ?" : ""}
+      ORDER BY rank LIMIT ?
+    `).all(...(args.namespace ? [args.namespace, limit] : [limit]));
+        return jsonResult({ chunks: rows, count: rows.length, mode: "keyword_only" });
+    }
+    const results = hybridSearch(db, "chunks_fts", "vec_chunks", args.query, queryEmbedding, limit * 2, alpha);
+    if (results.length === 0)
+        return jsonResult({ chunks: [], count: 0 });
+    const ids = results.map(r => r.rowid);
+    const scoreMap = new Map(results.map(r => [r.rowid, r.score]));
+    const conditions = [`c.id IN (${ids.map(() => "?").join(",")})`];
+    const vals = [...ids];
+    if (args.namespace) {
+        conditions.push("d.namespace = ?");
+        vals.push(args.namespace);
+    }
+    const rows = db.prepare(`
+    SELECT c.*, d.title as doc_title, d.source as doc_source, d.namespace as doc_namespace
+    FROM chunks c
+    JOIN documents d ON d.id = c.document_id
+    WHERE ${conditions.join(" AND ")}
+  `).all(...vals);
+    const scored = rows
+        .map(r => ({ ...r, _score: scoreMap.get(r.id) || 0 }))
+        .sort((a, b) => b._score - a._score)
+        .slice(0, limit);
+    return jsonResult({ chunks: scored, count: scored.length });
+}
+function docList(db, args) {
+    const conditions = [];
+    const vals = [];
+    if (args.namespace) {
+        conditions.push("namespace = ?");
+        vals.push(args.namespace);
+    }
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = args.limit || 50;
+    const rows = db.prepare(`
+    SELECT d.*, (SELECT COUNT(*) FROM chunks c WHERE c.document_id = d.id) as chunk_count
+    FROM documents d ${where}
+    ORDER BY d.created_at DESC LIMIT ?
+  `).all(...vals, limit);
+    return jsonResult({ documents: rows, count: rows.length });
+}
+function docGet(db, args) {
+    const doc = db.prepare("SELECT * FROM documents WHERE id = ?").get(args.id);
+    if (!doc)
+        return errorResult(`Document ${args.id} not found`);
+    const chunks = db.prepare("SELECT * FROM chunks WHERE document_id = ? ORDER BY chunk_index").all(args.id);
+    return jsonResult({ ...doc, chunks });
+}
+function docDelete(db, args) {
+    const chunks = db.prepare("SELECT id FROM chunks WHERE document_id = ?").all(args.id);
+    for (const c of chunks)
+        deleteVector(db, "vec_chunks", c.id);
+    db.prepare("DELETE FROM chunks WHERE document_id = ?").run(args.id);
+    db.prepare("DELETE FROM documents WHERE id = ?").run(args.id);
+    return jsonResult({ deleted: true, chunks_removed: chunks.length });
+}

package/dist/tools/episodes.d.ts

@@ -0,0 +1,112 @@
+import type Database from "better-sqlite3";
+export declare const episodeTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            session_id: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+            };
+            agent_role: {
+                type: string;
+                description: string;
+            };
+            role: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            summary: {
+                type: string;
+                description: string;
+            };
+            metadata: {
+                type: string;
+                description: string;
+            };
+            limit?: undefined;
+            order?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            session_id: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+            };
+            agent_role: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            order: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            role?: undefined;
+            content?: undefined;
+            summary?: undefined;
+            metadata?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            session_id: {
+                type: string;
+                description: string;
+            };
+            namespace: {
+                type: string;
+                description: string;
+            };
+            agent_role: {
+                type: string;
+                description: string;
+            };
+            summary: {
+                type: string;
+                description: string;
+            };
+            role?: undefined;
+            content?: undefined;
+            metadata?: undefined;
+            limit?: undefined;
+            order?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleEpisodes(db: Database.Database, name: string, args: any): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/tools/episodes.js

@@ -0,0 +1,98 @@
+import { createHash } from "node:crypto";
+import { now, jsonResult } from "../db.js";
+export const episodeTools = [
+    {
+        name: "memory.episode.log",
+        description: "Log a conversation turn or run event to episodic memory. Use for tracking what happened during agent runs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Session/run identifier" },
+                namespace: { type: "string", description: "Project or scope" },
+                agent_role: { type: "string", description: "Agent role" },
+                role: { type: "string", enum: ["user", "assistant", "system"], description: "Message role" },
+                content: { type: "string", description: "Message or event content" },
+                summary: { type: "string", description: "Optional short summary" },
+                metadata: { type: "object", description: "Custom metadata (e.g. tool calls, tokens used)" },
+            },
+            required: ["session_id", "role", "content"],
+        },
+    },
+    {
+        name: "memory.episode.list",
+        description: "List episodes for a session or namespace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Filter by session" },
+                namespace: { type: "string", description: "Filter by namespace" },
+                agent_role: { type: "string", description: "Filter by agent role" },
+                limit: { type: "number", description: "Max results (default 50)" },
+                order: { type: "string", enum: ["newest", "oldest"], description: "Default: oldest" },
+            },
+        },
+    },
+    {
+        name: "memory.episode.summarize",
+        description: "Store a summary for a session. The calling agent provides the summary text.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "string", description: "Session to summarize" },
+                namespace: { type: "string", description: "Scope" },
+                agent_role: { type: "string", description: "Agent role" },
+                summary: { type: "string", description: "Summary text" },
+            },
+            required: ["session_id", "summary"],
+        },
+    },
+];
+export function handleEpisodes(db, name, args) {
+    if (name === "memory.episode.log")
+        return episodeLog(db, args);
+    if (name === "memory.episode.list")
+        return episodeList(db, args);
+    if (name === "memory.episode.summarize")
+        return episodeSummarize(db, args);
+    return null;
+}
+function episodeLog(db, args) {
+    const ts = now();
+    const result = db.prepare(`
+    INSERT INTO episodes (session_id, namespace, agent_role, role, content, summary, metadata, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(args.session_id, args.namespace || null, args.agent_role || null, args.role, args.content, args.summary || null, JSON.stringify(args.metadata || {}), ts);
+    return jsonResult({ id: Number(result.lastInsertRowid), created: true });
+}
+function episodeList(db, args) {
+    const conditions = [];
+    const vals = [];
+    if (args.session_id) {
+        conditions.push("session_id = ?");
+        vals.push(args.session_id);
+    }
+    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 order = args.order === "newest" ? "DESC" : "ASC";
+    const limit = args.limit || 50;
+    const rows = db.prepare(`SELECT * FROM episodes ${where} ORDER BY created_at ${order} LIMIT ?`).all(...vals, limit);
+    return jsonResult({ episodes: rows, count: rows.length });
+}
+function episodeSummarize(db, args) {
+    // Update all episodes in the session with the summary
+    const result = db.prepare(`UPDATE episodes SET summary = ? WHERE session_id = ? AND summary IS NULL`).run(args.summary, args.session_id);
+    // Also store as a memory for cross-session recall
+    const ts = now();
+    db.prepare(`
+    INSERT INTO memories (memory_type, scope, namespace, agent_role, title, content, status, confidence, tags, metadata, created_at, occurred_at, updated_at, content_hash)
+    VALUES ('episodic', 'session', ?, ?, ?, ?, 'active', 1.0, '["session_summary"]', ?, ?, ?, ?, ?)
+  `).run(args.namespace || null, args.agent_role || null, `Session ${args.session_id} summary`, args.summary, JSON.stringify({ session_id: args.session_id }), ts, ts, ts, createHash("sha256").update(`episode\0${args.session_id}\0${args.summary}`).digest("hex"));
+    return jsonResult({ episodes_updated: result.changes, session_id: args.session_id });
+}