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

package/src/tools/context.ts

@@ -5,15 +5,15 @@ export const contextTools = [
   {
     name: "memory.context",
     description:
-      "Agent boot tool — call at the start of each run to load relevant memory. Returns recent entries, active decisions, cross-project patterns, summaries, and a summarization_needed flag.",
+      "Agent boot tool — call at the start of each run to load all relevant memory. Returns recent memories, active decisions, related entities, episode summaries, and document count. Scoped by namespace and agent role.",
     inputSchema: {
       type: "object" as const,
       properties: {
+        namespace: { type: "string", description: "Project/scope to load context for" },
         agent_role: { type: "string", description: "Agent role requesting context" },
-        project: { type: "string", description: "Project the agent is working on" },
         limit: { type: "number", description: "Max entries per section (default 10)" },
       },
-      required: ["agent_role", "project"],
+      required: ["namespace"],
     },
   },
 ];
@@ -24,53 +24,82 @@ export function handleContext(db: Database.Database, name: string, args: any) {
 }
 
 function memoryContext(db: Database.Database, args: any) {
-  const { agent_role, project } = args;
+  const { namespace, agent_role } = args;
   const limit = args.limit || 10;
 
-  const recentEntries = db.prepare(`
-    SELECT * FROM memory_entries
-    WHERE agent_role = ? AND project = ? AND status = 'active'
+  // Recent memories for this agent+namespace
+  const recentMemories = db.prepare(`
+    SELECT * FROM memories
+    WHERE namespace = ? ${agent_role ? "AND agent_role = ?" : ""}
+      AND status = 'active'
     ORDER BY occurred_at DESC LIMIT ?
-  `).all(agent_role, project, limit);
+  `).all(...(agent_role ? [namespace, agent_role, limit] : [namespace, limit]));
 
-  const activeDecisions = db.prepare(`
-    SELECT * FROM memory_entries
-    WHERE project = ? AND entry_type = 'decision' AND status = 'active'
-    ORDER BY occurred_at DESC LIMIT ?
-  `).all(project, limit);
+  // Active semantic memories (facts/knowledge) for this namespace
+  const knowledge = db.prepare(`
+    SELECT * FROM memories
+    WHERE namespace = ? AND memory_type = 'semantic' AND status = 'active'
+    ORDER BY confidence DESC, access_count DESC LIMIT ?
+  `).all(namespace, limit);
+
+  // Active procedural memories (how-to) for this namespace
+  const procedures = db.prepare(`
+    SELECT * FROM memories
+    WHERE namespace = ? AND memory_type = 'procedural' AND status = 'active'
+    ORDER BY access_count DESC LIMIT ?
+  `).all(namespace, limit);
 
-  const activePatterns = db.prepare(`
-    SELECT * FROM memory_patterns
-    WHERE status = 'active'
-      AND EXISTS (SELECT 1 FROM json_each(projects) WHERE json_each.value = ?)
-    ORDER BY last_seen DESC LIMIT ?
-  `).all(project, limit);
+  // Related entities
+  const entities = db.prepare(`
+    SELECT e.*, (SELECT COUNT(*) FROM relations r WHERE r.source_entity_id = e.id OR r.target_entity_id = e.id) as relation_count
+    FROM entities e
+    WHERE e.namespace = ?
+    ORDER BY relation_count DESC LIMIT ?
+  `).all(namespace, limit);
 
-  const recentSummaries = db.prepare(`
-    SELECT * FROM memory_summaries
-    WHERE agent_role = ? AND project = ?
-    ORDER BY created_at DESC LIMIT 5
-  `).all(agent_role, project);
+  // Recent episode summaries
+  const episodeSummaries = db.prepare(`
+    SELECT DISTINCT session_id, summary, MAX(created_at) as last_at
+    FROM episodes
+    WHERE namespace = ? AND summary IS NOT NULL
+    GROUP BY session_id
+    ORDER BY last_at DESC LIMIT 5
+  `).all(namespace);
 
-  const crossProjectAlerts = db.prepare(`
-    SELECT * FROM memory_patterns
-    WHERE status = 'active' AND occurrence_count >= 3
-    ORDER BY last_seen DESC LIMIT 5
+  // Document count
+  const docCount = (db.prepare(
+    "SELECT COUNT(*) as count FROM documents WHERE namespace = ?"
+  ).get(namespace) as any).count;
+
+  // Global memories (cross-project)
+  const globalMemories = db.prepare(`
+    SELECT * FROM memories
+    WHERE scope = 'global' AND status = 'active'
+    ORDER BY confidence DESC, occurred_at DESC LIMIT 5
   `).all();
 
-  // Check if summarization is needed: 20+ active entries older than 3 days
+  // Check if summarization needed
   const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString();
   const staleCount = (db.prepare(`
-    SELECT COUNT(*) as count FROM memory_entries
-    WHERE agent_role = ? AND project = ? AND status = 'active' AND occurred_at < ?
-  `).get(agent_role, project, threeDaysAgo) as any).count;
+    SELECT COUNT(*) as count FROM memories
+    WHERE namespace = ? ${agent_role ? "AND agent_role = ?" : ""}
+      AND status = 'active' AND occurred_at < ?
+  `).get(...(agent_role ? [namespace, agent_role, threeDaysAgo] : [namespace, threeDaysAgo])) as any).count;
+
+  // Stats
+  const totalMemories = (db.prepare(
+    "SELECT COUNT(*) as count FROM memories WHERE namespace = ? AND status = 'active'"
+  ).get(namespace) as any).count;
 
   return jsonResult({
-    recent_entries: recentEntries,
-    active_decisions: activeDecisions,
-    active_patterns: activePatterns,
-    recent_summaries: recentSummaries,
-    cross_project_alerts: crossProjectAlerts,
+    recent_memories: recentMemories,
+    knowledge,
+    procedures,
+    entities,
+    episode_summaries: episodeSummaries,
+    global_memories: globalMemories,
+    document_count: docCount,
+    total_active_memories: totalMemories,
     summarization_needed: staleCount >= 20,
     stale_entry_count: staleCount,
   });

package/src/tools/documents.ts

@@ -0,0 +1,215 @@
+import type Database from "better-sqlite3";
+import { now, jsonResult, errorResult, chunkText } from "../db.ts";
+import { embed, storeVector, deleteVector, hybridSearch } from "../embeddings.ts";
+
+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" as const,
+      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" as const,
+      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" as const,
+      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" as const,
+      properties: {
+        id: { type: "number", description: "Document ID" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "memory.doc.delete",
+    description: "Delete a document and all its chunks.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        id: { type: "number", description: "Document ID" },
+      },
+      required: ["id"],
+    },
+  },
+];
+
+export function handleDocuments(db: Database.Database, name: string, args: any) {
+  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: Database.Database, args: any) {
+  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) as any;
+    if (existing) {
+      // Re-ingest: delete old chunks
+      const oldChunks = db.prepare("SELECT id FROM chunks WHERE document_id = ?").all(existing.id) as any[];
+      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: number[] = [];
+  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: Database.Database, args: any) {
+  const limit = args.limit || 5;
+  const alpha = args.alpha ?? 0.6;
+
+  let queryEmbedding: Float32Array;
+  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: any[] = [...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) as any[];
+
+  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: Database.Database, args: any) {
+  const conditions: string[] = [];
+  const vals: any[] = [];
+  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: Database.Database, args: any) {
+  const doc = db.prepare("SELECT * FROM documents WHERE id = ?").get(args.id) as any;
+  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: Database.Database, args: any) {
+  const chunks = db.prepare("SELECT id FROM chunks WHERE document_id = ?").all(args.id) as any[];
+  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/src/tools/episodes.ts

@@ -0,0 +1,112 @@
+import type Database from "better-sqlite3";
+import { now, jsonResult, errorResult } from "../db.ts";
+
+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" as const,
+      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" as const,
+      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" as const,
+      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: Database.Database, name: string, args: any) {
+  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: Database.Database, args: any) {
+  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: Database.Database, args: any) {
+  const conditions: string[] = [];
+  const vals: any[] = [];
+  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: Database.Database, args: any) {
+  // 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,
+    require("node:crypto").createHash("sha256").update(`episode\0${args.session_id}\0${args.summary}`).digest("hex")
+  );
+
+  return jsonResult({ episodes_updated: result.changes, session_id: args.session_id });
+}