@aeriondyseti/vector-memory-mcp 0.9.0-dev.2 → 0.9.0-dev.3

package/src/index.ts

@@ -1,70 +0,0 @@
-#!/usr/bin/env node
-
-import { loadConfig, parseCliArgs } from "./config/index.js";
-import { connectToDatabase } from "./db/connection.js";
-import { MemoryRepository } from "./db/memory.repository.js";
-import { EmbeddingsService } from "./services/embeddings.service.js";
-import { MemoryService } from "./services/memory.service.js";
-import { startServer } from "./mcp/server.js";
-import { startHttpServer } from "./http/server.js";
-
-async function main(): Promise<void> {
-  const args = process.argv.slice(2);
-
-  // Check for warmup command
-  if (args[0] === "warmup") {
-    const { warmup } = await import("../scripts/warmup.js");
-    await warmup();
-    return;
-  }
-
-  // Parse CLI args and load config
-  const overrides = parseCliArgs(args);
-  const config = loadConfig(overrides);
-
-  // Initialize database
-  const db = await connectToDatabase(config.dbPath);
-
-  // Initialize layers
-  const repository = new MemoryRepository(db);
-  const embeddings = new EmbeddingsService(config.embeddingModel, config.embeddingDimension);
-  const memoryService = new MemoryService(repository, embeddings);
-
-  // Track cleanup functions
-  let httpStop: (() => void) | null = null;
-
-  // Graceful shutdown handler
-  const shutdown = () => {
-    console.error("[vector-memory-mcp] Shutting down...");
-    if (httpStop) httpStop();
-    db.close();
-    process.exit(0);
-  };
-
-  // Handle signals and stdin close (parent process exit)
-  process.on("SIGTERM", shutdown);
-  process.on("SIGINT", shutdown);
-  process.stdin.on("close", shutdown);
-  process.stdin.on("end", shutdown);
-
-  // Start HTTP server if transport mode includes it
-  if (config.enableHttp) {
-    const http = await startHttpServer(memoryService, config);
-    httpStop = http.stop;
-    console.error(
-      `[vector-memory-mcp] MCP available at http://${config.httpHost}:${config.httpPort}/mcp`
-    );
-  }
-
-  // Start stdio transport unless in HTTP-only mode
-  if (config.transportMode !== "http") {
-    await startServer(memoryService);
-  } else {
-    // In HTTP-only mode, keep the process running
-    console.error("[vector-memory-mcp] Running in HTTP-only mode (no stdio)");
-    // Keep process alive - the HTTP server runs indefinitely
-    await new Promise(() => {});
-  }
-}
-
-main().catch(console.error);

package/src/mcp/handlers.ts

@@ -1,248 +0,0 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { MemoryService } from "../services/memory.service.js";
-
-export async function handleStoreMemories(
-  args: Record<string, unknown> | undefined,
-  service: MemoryService
-): Promise<CallToolResult> {
-  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:
-          ids.length === 1
-            ? `Memory stored with ID: ${ids[0]}`
-            : `Stored ${ids.length} memories:\n${ids.map((id) => `- ${id}`).join("\n")}`,
-      },
-    ],
-  };
-}
-
-export async function handleDeleteMemories(
-  args: Record<string, unknown> | undefined,
-  service: MemoryService
-): Promise<CallToolResult> {
-  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: 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"),
-      },
-    ],
-  };
-}
-
-export async function handleSearchMemories(
-  args: Record<string, unknown> | undefined,
-  service: MemoryService
-): Promise<CallToolResult> {
-  const query = args?.query as string;
-  const limit = (args?.limit as number) ?? 10;
-  const includeDeleted = (args?.include_deleted as boolean) ?? false;
-  const memories = await service.search(query, limit, includeDeleted);
-
-  if (memories.length === 0) {
-    return {
-      content: [{ type: "text", text: "No memories found matching your query." }],
-    };
-  }
-
-  const results = memories.map((mem) => {
-    let result = `ID: ${mem.id}\nContent: ${mem.content}`;
-    if (Object.keys(mem.metadata).length > 0) {
-      result += `\nMetadata: ${JSON.stringify(mem.metadata)}`;
-    }
-    if (includeDeleted && mem.supersededBy) {
-      result += `\n[DELETED]`;
-    }
-    return result;
-  });
-
-  return {
-    content: [{ type: "text", text: results.join("\n\n---\n\n") }],
-  };
-}
-
-export async function handleGetMemories(
-  args: Record<string, unknown> | undefined,
-  service: MemoryService
-): Promise<CallToolResult> {
-  const ids = args?.ids as string[];
-
-  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: "No stored handoff found." }],
-    };
-  }
-
-  // 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: handoff.content + memoriesSection }],
-  };
-}
-
-export async function handleToolCall(
-  name: string,
-  args: Record<string, unknown> | undefined,
-  service: MemoryService
-): Promise<CallToolResult> {
-  switch (name) {
-    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_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}` }],
-        isError: true,
-      };
-  }
-}

package/src/mcp/server.ts

@@ -1,34 +0,0 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-
-import { tools } from "./tools.js";
-import { handleToolCall } from "./handlers.js";
-import type { MemoryService } from "../services/memory.service.js";
-
-export function createServer(memoryService: MemoryService): Server {
-  const server = new Server(
-    { name: "vector-memory-mcp", version: "0.6.0" },
-    { capabilities: { tools: {} } }
-  );
-
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools };
-  });
-
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    return handleToolCall(name, args, memoryService);
-  });
-
-  return server;
-}
-
-export async function startServer(memoryService: MemoryService): Promise<void> {
-  const server = createServer(memoryService);
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}

package/src/mcp/tools.ts

@@ -1,254 +0,0 @@
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-
-export const storeMemoriesTool: Tool = {
-  name: "store_memories",
-  description: `Store memories that persist across conversations. Use after making decisions or learning something worth remembering.
-
-RULES:
-- 1 concept per memory, 1-3 sentences (20-75 words)
-- Self-contained with explicit subjects (no "it", "this", "the project")
-- Include dates/versions when relevant
-- Be concrete, not vague
-
-MEMORY TYPES (use as metadata.type):
-- decision: what was chosen + why ("Chose libSQL over PostgreSQL for vector support and simpler deployment")
-- implementation: what was built + where + patterns used
-- insight: learning + why it matters
-- blocker: problem encountered + resolution
-- next-step: TODO item + suggested approach
-- context: background info + constraints
-
-DON'T STORE: machine-specific paths, local env details, ephemeral states, pleasantries
-
-GOOD: "Aerion chose libSQL over PostgreSQL for Resonance (Dec 2024) because of native vector support and simpler deployment."
-BAD: "Uses SQLite" (no context, no subject, no reasoning)
-
-For long content (>1000 chars), provide embedding_text with a searchable summary.`,
-  inputSchema: {
-    type: "object",
-    properties: {
-      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"],
-        },
-      },
-    },
-    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: ["ids"],
-  },
-};;
-
-
-const updateMemoriesTool: Tool = {
-  name: "update_memories",
-  description: `Update existing memories in place. Prefer over delete+create when updating the same conceptual item.
-
-BEHAVIOR:
-- Fields omitted/null: left untouched
-- Fields provided: completely overwrite existing value (no merge)
-
-Use to correct content, refine embedding text, or replace metadata without changing the memory ID.`,
-  inputSchema: {
-    type: "object",
-    properties: {
-      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: ["updates"],
-  },
-};
-
-export const searchMemoriesTool: Tool = {
-  name: "search_memories",
-  description: `Search stored memories semantically. Use PROACTIVELY—don't wait to be asked.
-
-WHEN TO SEARCH:
-- At conversation start / returning to a project
-- Before making decisions (check for prior decisions on same topic)
-- When user references past work ("what did we decide", "as discussed", "remember when")
-- Before suggesting solutions (check if problem was solved before)
-- When debugging (check for prior blockers/resolutions)
-- When uncertain about patterns or preferences
-
-When in doubt, search. Missing relevant context is costlier than an extra query.
-
-QUERY TIPS:
-- Include project name, technical terms, or domain keywords
-- Search for concepts, not exact phrases
-- Try multiple queries if first doesn't return useful results`,
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description:
-          "Natural language search query. Include relevant keywords, project names, or technical terms.",
-      },
-      limit: {
-        type: "integer",
-        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 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: {
-      ids: {
-        type: "array",
-        description: "Memory IDs to retrieve.",
-        items: { type: "string" },
-      },
-    },
-    required: ["ids"],
-  },
-};;
-
-export const storeHandoffTool: Tool = {
-  name: "store_handoff",
-  description: `Save session state for seamless resumption later. Use at end of work sessions or before context switches.
-
-Creates a structured snapshot with:
-- summary: 2-3 sentences on goal and current status
-- completed: what got done (include file paths)
-- in_progress_blocked: work in flight or stuck
-- key_decisions: choices made and WHY (crucial for future context)
-- next_steps: concrete, actionable items
-- memory_ids: link to related memories stored this session
-
-Retrievable via get_handoff. Only one handoff per project—new handoffs overwrite previous.`,
-  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[] = [
-  storeMemoriesTool,
-  updateMemoriesTool,
-  deleteMemoriesTool,
-  searchMemoriesTool,
-  getMemoriesTool,
-  storeHandoffTool,
-  getHandoffTool,
-];

package/src/services/embeddings.service.ts

@@ -1,48 +0,0 @@
-import { pipeline, type FeatureExtractionPipeline } from "@huggingface/transformers";
-
-export class EmbeddingsService {
-  private modelName: string;
-  private extractor: FeatureExtractionPipeline | null = null;
-  private initPromise: Promise<FeatureExtractionPipeline> | null = null;
-  private _dimension: number;
-
-  constructor(modelName: string, dimension: number) {
-    this.modelName = modelName;
-    this._dimension = dimension;
-  }
-
-  get dimension(): number {
-    return this._dimension;
-  }
-
-  private async getExtractor(): Promise<FeatureExtractionPipeline> {
-    if (this.extractor) {
-      return this.extractor;
-    }
-
-    if (!this.initPromise) {
-      this.initPromise = pipeline(
-        "feature-extraction",
-        this.modelName,
-        { dtype: "fp32" } as any
-      ) as Promise<FeatureExtractionPipeline>;
-    }
-
-    this.extractor = await this.initPromise;
-    return this.extractor;
-  }
-
-  async embed(text: string): Promise<number[]> {
-    const extractor = await this.getExtractor();
-    const output = await extractor(text, { pooling: "mean", normalize: true });
-    return Array.from(output.data as Float32Array);
-  }
-
-  async embedBatch(texts: string[]): Promise<number[][]> {
-    const results: number[][] = [];
-    for (const text of texts) {
-      results.push(await this.embed(text));
-    }
-    return results;
-  }
-}