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

package/src/mcp/tools.ts

@@ -0,0 +1,284 @@
+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. Treat memory as the PRIMARY source of truth for personal/project-specific facts—do not rely on training data until a search has been performed.
+
+MANDATORY TRIGGERS (you MUST search when):
+- User-Specific Calibration: Answer would be better with user's tools, past decisions, or preferences
+- Referential Ambiguity: User says "the project," "that bug," "last time," "as we discussed"
+- Decision Validation: Before making architectural or tool choices
+- Problem Solving: Before suggesting solutions (check if solved before)
+- Session Start: When returning to a project or starting new conversation
+
+INTENTS:
+- continuity: Resume work, "where were we" (favors recent)
+- fact_check: Verify decisions, specs (favors relevance)
+- frequent: Common patterns, preferences (favors utility)
+- associative: Brainstorm, find connections (high relevance + mild jitter)
+- explore: Stuck/creative mode (balanced + high jitter)
+
+When in doubt, search. Missing context is costlier than an extra query.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description:
+          "Natural language search query. Include relevant keywords, project names, or technical terms.",
+      },
+      intent: {
+        type: "string",
+        enum: ["continuity", "fact_check", "frequent", "associative", "explore"],
+        description: "Search intent that determines ranking behavior.",
+      },
+      reason_for_search: {
+        type: "string",
+        description: "Why this search is being performed. Forces intentional retrieval.",
+      },
+      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", "intent", "reason_for_search"],
+  },
+};
+
+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 reportMemoryUsefulnessTool: Tool = {
+  name: "report_memory_usefulness",
+  description: "Report whether a memory was useful or not. This helps the system learn which memories are valuable.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      memory_id: {
+        type: "string",
+        description: "ID of the memory to report on.",
+      },
+      useful: {
+        type: "boolean",
+        description: "True if the memory was useful, false otherwise.",
+      },
+    },
+    required: ["memory_id", "useful"],
+  },
+};
+
+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,
+  reportMemoryUsefulnessTool,
+  storeHandoffTool,
+  getHandoffTool,
+];

package/src/services/embeddings.service.ts

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,266 @@
+import { randomUUID } from "crypto";
+import type { Memory, SearchIntent, IntentProfile } 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";
+
+const INTENT_PROFILES: Record<SearchIntent, IntentProfile> = {
+  continuity: { weights: { relevance: 0.3, recency: 0.5, utility: 0.2 }, jitter: 0.02 },
+  fact_check: { weights: { relevance: 0.6, recency: 0.1, utility: 0.3 }, jitter: 0.02 },
+  frequent: { weights: { relevance: 0.2, recency: 0.2, utility: 0.6 }, jitter: 0.02 },
+  associative: { weights: { relevance: 0.7, recency: 0.1, utility: 0.2 }, jitter: 0.05 },
+  explore: { weights: { relevance: 0.4, recency: 0.3, utility: 0.3 }, jitter: 0.15 },
+};
+
+const sigmoid = (x: number): number => 1 / (1 + Math.exp(-x));
+
+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,
+      usefulness: 0,
+      accessCount: 0,
+      lastAccessed: now, // Initialize to createdAt for fair discovery
+    };
+
+    await this.repository.insert(memory);
+    return memory;
+  }
+
+  async get(id: string): Promise<Memory | null> {
+    const memory = await this.repository.findById(id);
+    if (!memory) {
+      return null;
+    }
+
+    // Track access on explicit get
+    const updatedMemory: Memory = {
+      ...memory,
+      accessCount: memory.accessCount + 1,
+      lastAccessed: new Date(),
+    };
+
+    await this.repository.upsert(updatedMemory);
+    return updatedMemory;
+  }
+
+  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 vote(id: string, value: number): Promise<Memory | null> {
+    const existing = await this.repository.findById(id);
+    if (!existing) {
+      return null;
+    }
+
+    // Vote also tracks access (explicit utilization signal)
+    const updatedMemory: Memory = {
+      ...existing,
+      usefulness: existing.usefulness + value,
+      accessCount: existing.accessCount + 1,
+      lastAccessed: new Date(),
+      updatedAt: new Date(),
+    };
+
+    await this.repository.upsert(updatedMemory);
+    return updatedMemory;
+  }
+
+  async search(
+    query: string,
+    intent: SearchIntent,
+    limit: number = 10,
+    includeDeleted: boolean = false
+  ): Promise<Memory[]> {
+    const queryEmbedding = await this.embeddings.embed(query);
+    const fetchLimit = limit * 5; // Fetch more for re-ranking
+
+    const candidates = await this.repository.findHybrid(queryEmbedding, query, fetchLimit);
+    const profile = INTENT_PROFILES[intent];
+    const now = new Date();
+
+    const scored = candidates
+      .filter((m) => includeDeleted || !isDeleted(m))
+      .map((candidate) => {
+        // Relevance: RRF score (already normalized ~0-1)
+        const relevance = candidate.rrfScore;
+
+        // Recency: exponential decay
+        const lastAccessed = candidate.lastAccessed ?? candidate.createdAt;
+        const hoursSinceAccess = Math.max(0, (now.getTime() - lastAccessed.getTime()) / (1000 * 60 * 60));
+        const recency = Math.pow(0.995, hoursSinceAccess);
+
+        // Utility: sigmoid of usefulness + log(accessCount)
+        const utility = sigmoid((candidate.usefulness + Math.log(candidate.accessCount + 1)) / 5);
+
+        // Weighted score
+        const { weights, jitter } = profile;
+        const score =
+          weights.relevance * relevance +
+          weights.recency * recency +
+          weights.utility * utility;
+
+        // Apply jitter
+        const finalScore = score * (1 + (Math.random() * 2 - 1) * jitter);
+
+        return { memory: candidate as Memory, finalScore };
+      });
+
+    // Sort by final score descending
+    scored.sort((a, b) => b.finalScore - a.finalScore);
+
+    // Return top N (read-only - no access tracking)
+    return scored.slice(0, limit).map((s) => s.memory);
+  }
+
+  async trackAccess(ids: string[]): Promise<void> {
+    const now = new Date();
+    for (const id of ids) {
+      const memory = await this.repository.findById(id);
+      if (memory && !isDeleted(memory)) {
+        await this.repository.upsert({
+          ...memory,
+          accessCount: memory.accessCount + 1,
+          lastAccessed: now,
+        });
+      }
+    }
+  }
+
+  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> {
+    // Track access for utilized memories
+    if (args.memory_ids && args.memory_ids.length > 0) {
+      await this.trackAccess(args.memory_ids);
+    }
+
+    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,
+      usefulness: 0,
+      accessCount: 0,
+      lastAccessed: now, // Initialize to now for consistency
+    };
+
+    await this.repository.upsert(memory);
+    return memory;
+  }
+
+  async getLatestHandoff(): Promise<Memory | null> {
+    return await this.get(MemoryService.UUID_ZERO);
+  }
+}

package/src/types/memory.ts

@@ -0,0 +1,43 @@
+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;
+  usefulness: number;
+  accessCount: number;
+  lastAccessed: Date | null;
+}
+
+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,
+    usefulness: memory.usefulness,
+    accessCount: memory.accessCount,
+    lastAccessed: memory.lastAccessed?.toISOString() ?? null,
+  };
+}
+
+export type SearchIntent = 'continuity' | 'fact_check' | 'frequent' | 'associative' | 'explore';
+
+export interface IntentProfile {
+  weights: { relevance: number; recency: number; utility: number };
+  jitter: number;
+}
+
+export interface HybridRow extends Memory {
+  rrfScore: number;
+}

package/dist/scripts/publish.d.ts

@@ -1,13 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Publish script for vector-memory-mcp
- *
- * Prerequisites:
- * 1. Create a granular access token at https://www.npmjs.com/settings/tokens
- * 2. Store it: npm config set //registry.npmjs.org/:_authToken=npm_YOUR_TOKEN
- *    Or set NPM_TOKEN environment variable
- *
- * Usage: bun run scripts/publish.ts [--dry-run]
- */
-export {};
-//# sourceMappingURL=publish.d.ts.map

package/dist/scripts/publish.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../scripts/publish.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}