@aeriondyseti/vector-memory-mcp 0.5.0 → 0.8.0

package/src/mcp/handlers.ts

@@ -1,34 +1,96 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { MemoryService } from "../services/memory.service.js";
 
-export async function handleStoreMemory(
+export async function handleStoreMemories(
   args: Record<string, unknown> | undefined,
   service: MemoryService
 ): Promise<CallToolResult> {
-  const content = args?.content as string;
-  const embeddingText = args?.embedding_text as string | undefined;
-  const metadata = (args?.metadata as Record<string, unknown>) ?? {};
-  const memory = await service.store(content, metadata, embeddingText);
+  const memories = args?.memories as Array<{
+    content: string;
+    embedding_text?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+
+  const ids: string[] = [];
+  for (const item of memories) {
+    const memory = await service.store(
+      item.content,
+      item.metadata ?? {},
+      item.embedding_text
+    );
+    ids.push(memory.id);
+  }
 
   return {
-    content: [{ type: "text", text: `Memory stored with ID: ${memory.id}` }],
+    content: [
+      {
+        type: "text",
+        text:
+          ids.length === 1
+            ? `Memory stored with ID: ${ids[0]}`
+            : `Stored ${ids.length} memories:\n${ids.map((id) => `- ${id}`).join("\n")}`,
+      },
+    ],
   };
 }
 
-export async function handleDeleteMemory(
+export async function handleDeleteMemories(
   args: Record<string, unknown> | undefined,
   service: MemoryService
 ): Promise<CallToolResult> {
-  const id = args?.id as string;
-  const success = await service.delete(id);
+  const ids = args?.ids as string[];
+  const results: string[] = [];
+
+  for (const id of ids) {
+    const success = await service.delete(id);
+    results.push(
+      success ? `Memory ${id} deleted successfully` : `Memory ${id} not found`
+    );
+  }
 
   return {
     content: [
       {
         type: "text",
-        text: success
-          ? `Memory ${id} deleted successfully`
-          : `Memory ${id} not found`,
+        text: results.join("\n"),
+      },
+    ],
+  };
+}
+
+
+export async function handleUpdateMemories(
+  args: Record<string, unknown> | undefined,
+  service: MemoryService
+): Promise<CallToolResult> {
+  const updates = args?.updates as Array<{
+    id: string;
+    content?: string;
+    embedding_text?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+
+  const results: string[] = [];
+
+  for (const update of updates) {
+    const memory = await service.update(update.id, {
+      content: update.content,
+      embeddingText: update.embedding_text,
+      metadata: update.metadata,
+    });
+
+    if (memory) {
+      results.push(`Memory ${update.id} updated successfully`);
+    } else {
+      results.push(`Memory ${update.id} not found`);
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: results.join("\n"),
       },
     ],
   };
@@ -40,7 +102,8 @@ export async function handleSearchMemories(
 ): Promise<CallToolResult> {
   const query = args?.query as string;
   const limit = (args?.limit as number) ?? 10;
-  const memories = await service.search(query, limit);
+  const includeDeleted = (args?.include_deleted as boolean) ?? false;
+  const memories = await service.search(query, limit, includeDeleted);
 
   if (memories.length === 0) {
     return {
@@ -53,6 +116,9 @@ export async function handleSearchMemories(
     if (Object.keys(mem.metadata).length > 0) {
       result += `\nMetadata: ${JSON.stringify(mem.metadata)}`;
     }
+    if (includeDeleted && mem.supersededBy) {
+      result += `\n[DELETED]`;
+    }
     return result;
   });
 
@@ -61,31 +127,95 @@ export async function handleSearchMemories(
   };
 }
 
-export async function handleGetMemory(
+export async function handleGetMemories(
   args: Record<string, unknown> | undefined,
   service: MemoryService
 ): Promise<CallToolResult> {
-  const id = args?.id as string;
-  const memory = await service.get(id);
+  const ids = args?.ids as string[];
 
-  if (!memory) {
+  const format = (
+    memoryId: string,
+    memory: Awaited<ReturnType<MemoryService["get"]>>
+  ) => {
+    if (!memory) {
+      return `Memory ${memoryId} not found`;
+    }
+
+    let result = `ID: ${memory.id}\nContent: ${memory.content}`;
+    if (Object.keys(memory.metadata).length > 0) {
+      result += `\nMetadata: ${JSON.stringify(memory.metadata)}`;
+    }
+    result += `\nCreated: ${memory.createdAt.toISOString()}`;
+    result += `\nUpdated: ${memory.updatedAt.toISOString()}`;
+    if (memory.supersededBy) {
+      result += `\nSuperseded by: ${memory.supersededBy}`;
+    }
+    return result;
+  };
+
+  const blocks: string[] = [];
+  for (const id of ids) {
+    const memory = await service.get(id);
+    blocks.push(format(id, memory));
+  }
+
+  return {
+    content: [{ type: "text", text: blocks.join("\n\n---\n\n") }],
+  };
+}
+
+export async function handleStoreHandoff(
+  args: Record<string, unknown> | undefined,
+  service: MemoryService
+): Promise<CallToolResult> {
+  const memory = await service.storeHandoff({
+    project: args?.project as string,
+    branch: args?.branch as string | undefined,
+    summary: args?.summary as string,
+    completed: (args?.completed as string[] | undefined) ?? [],
+    in_progress_blocked: (args?.in_progress_blocked as string[] | undefined) ?? [],
+    key_decisions: (args?.key_decisions as string[] | undefined) ?? [],
+    next_steps: (args?.next_steps as string[] | undefined) ?? [],
+    memory_ids: (args?.memory_ids as string[] | undefined) ?? [],
+    metadata: (args?.metadata as Record<string, unknown>) ?? {},
+  });
+
+  return {
+    content: [{ type: "text", text: `Handoff stored with memory ID: ${memory.id}` }],
+  };
+}
+
+export async function handleGetHandoff(
+  _args: Record<string, unknown> | undefined,
+  service: MemoryService
+): Promise<CallToolResult> {
+  const handoff = await service.getLatestHandoff();
+
+  if (!handoff) {
     return {
-      content: [{ type: "text", text: `Memory ${id} not found` }],
+      content: [{ type: "text", text: "No stored handoff found." }],
     };
   }
 
-  let result = `ID: ${memory.id}\nContent: ${memory.content}`;
-  if (Object.keys(memory.metadata).length > 0) {
-    result += `\nMetadata: ${JSON.stringify(memory.metadata)}`;
-  }
-  result += `\nCreated: ${memory.createdAt.toISOString()}`;
-  result += `\nUpdated: ${memory.updatedAt.toISOString()}`;
-  if (memory.supersededBy) {
-    result += `\nSuperseded by: ${memory.supersededBy}`;
+  // Fetch referenced memories if any
+  const memoryIds = (handoff.metadata.memory_ids as string[] | undefined) ?? [];
+  let memoriesSection = "";
+
+  if (memoryIds.length > 0) {
+    const memories: string[] = [];
+    for (const id of memoryIds) {
+      const memory = await service.get(id);
+      if (memory) {
+        memories.push(`### Memory: ${id}\n${memory.content}`);
+      }
+    }
+    if (memories.length > 0) {
+      memoriesSection = `\n\n## Referenced Memories\n\n${memories.join("\n\n")}`;
+    }
   }
 
   return {
-    content: [{ type: "text", text: result }],
+    content: [{ type: "text", text: handoff.content + memoriesSection }],
   };
 }
 
@@ -95,14 +225,20 @@ export async function handleToolCall(
   service: MemoryService
 ): Promise<CallToolResult> {
   switch (name) {
-    case "store_memory":
-      return handleStoreMemory(args, service);
-    case "delete_memory":
-      return handleDeleteMemory(args, service);
+    case "store_memories":
+      return handleStoreMemories(args, service);
+    case "update_memories":
+      return handleUpdateMemories(args, service);
+    case "delete_memories":
+      return handleDeleteMemories(args, service);
     case "search_memories":
       return handleSearchMemories(args, service);
-    case "get_memory":
-      return handleGetMemory(args, service);
+    case "get_memories":
+      return handleGetMemories(args, service);
+    case "store_handoff":
+      return handleStoreHandoff(args, service);
+    case "get_handoff":
+      return handleGetHandoff(args, service);
     default:
       return {
         content: [{ type: "text", text: `Unknown tool: ${name}` }],

package/src/mcp/server.ts

@@ -11,7 +11,7 @@ import type { MemoryService } from "../services/memory.service.js";
 
 export function createServer(memoryService: MemoryService): Server {
   const server = new Server(
-    { name: "vector-memory-mcp", version: "0.2.0" },
+    { name: "vector-memory-mcp", version: "0.6.0" },
     { capabilities: { tools: {} } }
   );
 

package/src/mcp/tools.ts

@@ -1,109 +1,214 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 
-export const storeMemoryTool: Tool = {
-  name: "store_memory",
+export const storeMemoriesTool: Tool = {
+  name: "store_memories",
   description:
-    "Store a new memory for later recall. " +
-    "PROACTIVELY store memories when: " +
-    "(1) Important decisions are made (technical choices, architecture decisions, tradeoffs); " +
-    "(2) Problems are solved (bugs fixed, errors resolved - include the solution); " +
-    "(3) User preferences or conventions are established; " +
-    "(4) Project-specific patterns or configurations are discussed; " +
-    "(5) Key information would be valuable in future sessions. " +
-    "IMPORTANT: If the content exceeds 1000 characters, you MUST provide an embedding_text " +
-    "parameter with a concise summary (under 1000 characters) that captures the key semantic " +
-    "meaning for search purposes. The full content will still be stored and returned in search results.",
+    "Build persistent memory across conversations. Store decisions, solutions, user preferences, " +
+    "patterns, or anything worth remembering. Batch related items in one call. " +
+    "For long content (>1000 chars), provide embedding_text with a searchable summary.",
   inputSchema: {
     type: "object",
     properties: {
-      content: {
-        type: "string",
-        description:
-          "The text content to store. Write in a way that will be useful when retrieved later - " +
-          "include context, reasoning, and outcomes, not just bare facts.",
-      },
-      embedding_text: {
-        type: "string",
-        description:
-          "A concise summary (under 1000 characters) used for generating the search embedding. " +
-          "REQUIRED when content exceeds 1000 characters. Should capture the key topics and terms " +
-          "someone might search for to find this memory.",
+      memories: {
+        type: "array",
+        description: "Memories to store.",
+        items: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: "The content to store.",
+            },
+            embedding_text: {
+              type: "string",
+              description:
+                "Summary for search embedding (required if content >1000 chars).",
+            },
+            metadata: {
+              type: "object",
+              description: "Optional key-value metadata.",
+              additionalProperties: true,
+            },
+          },
+          required: ["content"],
+        },
       },
-      metadata: {
-        type: "object",
-        description:
-          "Optional key-value metadata. Recommended keys: 'project' (project name), 'type' (decision/solution/preference/pattern), 'tags' (array of keywords).",
-        additionalProperties: true,
+    },
+    required: ["memories"],
+  },
+};;
+
+export const deleteMemoriesTool: Tool = {
+  name: "delete_memories",
+  description:
+    "Remove memories that are no longer needed—outdated info, superseded decisions, or incorrect content. " +
+    "Deleted memories can be recovered via search_memories with include_deleted: true.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ids: {
+        type: "array",
+        description: "IDs of memories to delete.",
+        items: {
+          type: "string",
+        },
       },
     },
-    required: ["content"],
+    required: ["ids"],
   },
-};
+};;
 
-export const deleteMemoryTool: Tool = {
-  name: "delete_memory",
+
+const updateMemoriesTool: Tool = {
+  name: "update_memories",
   description:
-    "Delete a memory by its ID. The memory will be soft-deleted and won't appear in search results.",
+    "Update existing memories in place. Use to correct content, refine embedding text, or replace metadata " +
+    "without changing the memory ID. Prefer over delete+create when updating the same conceptual item.",
   inputSchema: {
     type: "object",
     properties: {
-      id: {
-        type: "string",
-        description: "The ID of the memory to delete",
+      updates: {
+        type: "array",
+        description: "Updates to apply. Each must include id and at least one field to change.",
+        items: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string",
+              description: "ID of memory to update.",
+            },
+            content: {
+              type: "string",
+              description: "New content (triggers embedding regeneration).",
+            },
+            embedding_text: {
+              type: "string",
+              description: "New embedding summary (triggers embedding regeneration).",
+            },
+            metadata: {
+              type: "object",
+              description: "New metadata (replaces existing entirely).",
+              additionalProperties: true,
+            },
+          },
+          required: ["id"],
+        },
       },
     },
-    required: ["id"],
+    required: ["updates"],
   },
 };
 
 export const searchMemoriesTool: Tool = {
   name: "search_memories",
   description:
-    "Search for memories using semantic similarity. Returns the most relevant memories for the given query. " +
-    "IMPORTANT: Use this tool PROACTIVELY without being asked when you detect: " +
-    "(1) References to past decisions or discussions ('what did we decide', 'as we discussed', 'previously'); " +
-    "(2) Questions about prior work ('how did we', 'similar to before', 'like last time'); " +
-    "(3) Project continuations or returning to earlier topics; " +
-    "(4) Debugging issues that may have been solved before; " +
-    "(5) Questions about established patterns, conventions, or preferences. " +
-    "When in doubt, search - it's better to check for relevant context than to miss important prior decisions.",
+    "Search stored memories semantically. Use PROACTIVELY—don't wait to be asked. " +
+    "Triggers: references to past decisions ('what did we decide', 'as discussed'), " +
+    "questions about prior work, returning to a project, debugging something potentially solved before, " +
+    "or questions about established patterns/preferences. " +
+    "When uncertain, search—missing relevant memories is costlier than an extra query.",
   inputSchema: {
     type: "object",
     properties: {
       query: {
         type: "string",
         description:
-          "The search query to find relevant memories. Use natural language describing what context you need. " +
-          "Include relevant keywords, project names, or technical terms for better results.",
+          "Natural language search query. Include relevant keywords, project names, or technical terms.",
       },
       limit: {
         type: "integer",
-        description: "Maximum number of results to return (default: 10)",
+        description: "Maximum results to return (default: 10).",
         default: 10,
       },
+      include_deleted: {
+        type: "boolean",
+        description: "Include soft-deleted memories in results (default: false). Useful for recovering prior information.",
+        default: false,
+      },
     },
     required: ["query"],
   },
 };
 
-export const getMemoryTool: Tool = {
-  name: "get_memory",
-  description: "Retrieve a specific memory by its ID.",
+export const getMemoriesTool: Tool = {
+  name: "get_memories",
+  description:
+    "Retrieve full memory details by ID. Use when you have specific IDs from search results or prior references—otherwise use search_memories.",
   inputSchema: {
     type: "object",
     properties: {
-      id: {
-        type: "string",
-        description: "The ID of the memory to retrieve",
+      ids: {
+        type: "array",
+        description: "Memory IDs to retrieve.",
+        items: { type: "string" },
       },
     },
-    required: ["id"],
+    required: ["ids"],
+  },
+};;
+
+export const storeHandoffTool: Tool = {
+  name: "store_handoff",
+  description:
+    "Capture structured project state for handoff: summary, completed work, blockers, key decisions, next steps. " +
+    "Retrievable via get_handoff.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project: { type: "string", description: "Project name." },
+      branch: { type: "string", description: "Branch name (optional)." },
+      summary: { type: "string", description: "2-3 sentences: primary goal, current status." },
+      completed: {
+        type: "array",
+        items: { type: "string" },
+        description: "Completed items (include file paths where relevant).",
+      },
+      in_progress_blocked: {
+        type: "array",
+        items: { type: "string" },
+        description: "In progress or blocked items.",
+      },
+      key_decisions: {
+        type: "array",
+        items: { type: "string" },
+        description: "Decisions made and why.",
+      },
+      next_steps: {
+        type: "array",
+        items: { type: "string" },
+        description: "Concrete next steps.",
+      },
+      memory_ids: {
+        type: "array",
+        items: { type: "string" },
+        description: "Memory IDs referenced by this handoff.",
+      },
+      metadata: {
+        type: "object",
+        description: "Additional metadata.",
+        additionalProperties: true,
+      },
+    },
+    required: ["project", "summary"],
+  },
+};
+
+export const getHandoffTool: Tool = {
+  name: "get_handoff",
+  description:
+    "Load the current project handoff snapshot. Call at conversation start or when resuming a project.",
+  inputSchema: {
+    type: "object",
+    properties: {},
   },
 };
 
 export const tools: Tool[] = [
-  storeMemoryTool,
-  deleteMemoryTool,
+  storeMemoriesTool,
+  updateMemoriesTool,
+  deleteMemoriesTool,
   searchMemoriesTool,
-  getMemoryTool,
+  getMemoriesTool,
+  storeHandoffTool,
+  getHandoffTool,
 ];

package/src/services/embeddings.service.ts

@@ -21,9 +21,11 @@ export class EmbeddingsService {
     }
 
     if (!this.initPromise) {
-      this.initPromise = pipeline("feature-extraction", this.modelName, {
-        quantized: true,
-      }) as Promise<FeatureExtractionPipeline>;
+      this.initPromise = pipeline(
+        "feature-extraction",
+        this.modelName,
+        { dtype: "fp32" } as any
+      ) as Promise<FeatureExtractionPipeline>;
     }
 
     this.extractor = await this.initPromise;