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

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;
-  }
-}

package/src/services/memory.service.ts

@@ -1,185 +0,0 @@
-import { randomUUID } from "crypto";
-import type { Memory } from "../types/memory.js";
-import { isDeleted } from "../types/memory.js";
-import type { MemoryRepository } from "../db/memory.repository.js";
-import type { EmbeddingsService } from "./embeddings.service.js";
-
-export class MemoryService {
-  constructor(
-    private repository: MemoryRepository,
-    private embeddings: EmbeddingsService
-  ) {}
-
-  async store(
-    content: string,
-    metadata: Record<string, unknown> = {},
-    embeddingText?: string
-  ): Promise<Memory> {
-    const id = randomUUID();
-    const now = new Date();
-    const textToEmbed = embeddingText ?? content;
-    const embedding = await this.embeddings.embed(textToEmbed);
-
-    const memory: Memory = {
-      id,
-      content,
-      embedding,
-      metadata,
-      createdAt: now,
-      updatedAt: now,
-      supersededBy: null,
-    };
-
-    await this.repository.insert(memory);
-    return memory;
-  }
-
-  async get(id: string): Promise<Memory | null> {
-    return await this.repository.findById(id);
-  }
-
-  async delete(id: string): Promise<boolean> {
-    return await this.repository.markDeleted(id);
-  }
-
-
-  async update(
-    id: string,
-    updates: {
-      content?: string;
-      embeddingText?: string;
-      metadata?: Record<string, unknown>;
-    }
-  ): Promise<Memory | null> {
-    const existing = await this.repository.findById(id);
-    if (!existing) {
-      return null;
-    }
-
-    const newContent = updates.content ?? existing.content;
-    const newMetadata = updates.metadata ?? existing.metadata;
-
-    // Regenerate embedding if content or embeddingText changed
-    let newEmbedding = existing.embedding;
-    if (updates.content !== undefined || updates.embeddingText !== undefined) {
-      const textToEmbed = updates.embeddingText ?? newContent;
-      newEmbedding = await this.embeddings.embed(textToEmbed);
-    }
-
-    const updatedMemory: Memory = {
-      ...existing,
-      content: newContent,
-      embedding: newEmbedding,
-      metadata: newMetadata,
-      updatedAt: new Date(),
-    };
-
-    await this.repository.upsert(updatedMemory);
-    return updatedMemory;
-  }
-
-  async search(
-    query: string,
-    limit: number = 10,
-    includeDeleted: boolean = false
-  ): Promise<Memory[]> {
-    const queryEmbedding = await this.embeddings.embed(query);
-    const fetchLimit = limit * 3;
-
-    const rows = await this.repository.findSimilar(queryEmbedding, fetchLimit);
-
-    const results: Memory[] = [];
-
-    for (const row of rows) {
-      const memory = await this.repository.findById(row.id);
-
-      if (!memory) {
-        continue;
-      }
-
-      if (!includeDeleted && isDeleted(memory)) {
-        continue;
-      }
-
-      results.push(memory);
-      if (results.length >= limit) {
-        break;
-      }
-    }
-
-    return results;
-  }
-
-  private static readonly UUID_ZERO =
-    "00000000-0000-0000-0000-000000000000";
-
-  async storeHandoff(args: {
-    project: string;
-    branch?: string;
-    summary: string;
-    completed?: string[];
-    in_progress_blocked?: string[];
-    key_decisions?: string[];
-    next_steps?: string[];
-    memory_ids?: string[];
-    metadata?: Record<string, unknown>;
-  }): Promise<Memory> {
-    const now = new Date();
-    const date = now.toISOString().slice(0, 10);
-    const time = now.toISOString().slice(11, 16);
-
-    const list = (items: string[] | undefined) => {
-      if (!items || items.length === 0) {
-        return "- (none)";
-      }
-      return items.map((i) => `- ${i}`).join("\n");
-    };
-
-    const content = `# Handoff - ${args.project}
-**Date:** ${date} ${time} | **Branch:** ${args.branch ?? "unknown"}
-
-## Summary
-${args.summary}
-
-## Completed
-${list(args.completed)}
-
-## In Progress / Blocked
-${list(args.in_progress_blocked)}
-
-## Key Decisions
-${list(args.key_decisions)}
-
-## Next Steps
-${list(args.next_steps)}
-
-## Memory IDs
-${list(args.memory_ids)}`;
-
-    const metadata: Record<string, unknown> = {
-      ...(args.metadata ?? {}),
-      type: "handoff",
-      project: args.project,
-      date,
-      branch: args.branch ?? "unknown",
-      memory_ids: args.memory_ids ?? [],
-    };
-
-    const memory: Memory = {
-      id: MemoryService.UUID_ZERO,
-      content,
-      embedding: new Array(this.embeddings.dimension).fill(0),
-      metadata,
-      createdAt: now,
-      updatedAt: now,
-      supersededBy: null,
-    };
-
-    await this.repository.upsert(memory);
-    return memory;
-  }
-
-  async getLatestHandoff(): Promise<Memory | null> {
-    return await this.get(MemoryService.UUID_ZERO);
-  }
-}

package/src/types/memory.ts

@@ -1,31 +0,0 @@
-export const DELETED_TOMBSTONE = "DELETED";
-
-export interface Memory {
-  id: string;
-  content: string;
-  embedding: number[];
-  metadata: Record<string, unknown>;
-  createdAt: Date;
-  updatedAt: Date;
-  supersededBy: string | null;
-}
-
-export interface VectorRow {
-  id: string;
-  distance: number;
-}
-
-export function isDeleted(memory: Memory): boolean {
-  return memory.supersededBy === DELETED_TOMBSTONE;
-}
-
-export function memoryToDict(memory: Memory): Record<string, unknown> {
-  return {
-    id: memory.id,
-    content: memory.content,
-    metadata: memory.metadata,
-    createdAt: memory.createdAt.toISOString(),
-    updatedAt: memory.updatedAt.toISOString(),
-    supersededBy: memory.supersededBy,
-  };
-}