@aeriondyseti/vector-memory-mcp 2.4.4 → 2.5.0-dev.2

package/server/transports/mcp/handlers.ts

@@ -3,6 +3,7 @@ import type { MemoryService } from "../../core/memory.service";
 import type { ConversationHistoryService } from "../../core/conversation.service";
 import type { SearchIntent } from "../../core/memory";
 import type { HistoryFilters, SearchResult } from "../../core/conversation";
+import { resolveDateFilters } from "../../core/time-expr";
 import { DEBUG } from "../../config/index";
 
 /**
@@ -59,6 +60,32 @@ function requireString(args: Record<string, unknown> | undefined, field: string)
   return value;
 }
 
+const VALID_INTENTS = new Set(["continuity", "fact_check", "frequent", "associative", "explore"]);
+
+function asIntent(value: unknown): SearchIntent {
+  if (typeof value === "string" && VALID_INTENTS.has(value)) return value as SearchIntent;
+  return "fact_check";
+}
+
+function asInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(value)));
+}
+
+function asBool(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
 export async function handleStoreMemories(
   args: Record<string, unknown> | undefined,
   service: MemoryService
@@ -67,6 +94,7 @@ export async function handleStoreMemories(
     content: string;
     embedding_text?: string;
     metadata?: Record<string, unknown>;
+    project?: string;
   }>;
   try {
     memories = asArray(args?.memories, "memories");
@@ -79,7 +107,8 @@ export async function handleStoreMemories(
     const memory = await service.store(
       item.content,
       item.metadata ?? {},
-      item.embedding_text
+      item.embedding_text,
+      typeof item.project === "string" ? item.project : undefined
     );
     ids.push(memory.id);
   }
@@ -182,13 +211,13 @@ export async function handleSearchMemories(
   if (typeof query !== "string" || query.trim() === "") {
     return errorResult("query is required and must be a non-empty string");
   }
-  const intent = (args?.intent as SearchIntent) ?? "fact_check";
-  const limit = (args?.limit as number) ?? 10;
-  const offset = (args?.offset as number) ?? 0;
-  const includeDeleted = (args?.include_deleted as boolean) ?? false;
-  const historyOnly = (args?.history_only as boolean) ?? false;
+  const intent = asIntent(args?.intent);
+  const limit = asInt(args?.limit, 10, 1, 1000);
+  const offset = asInt(args?.offset, 0, 0, 10000);
+  const includeDeleted = asBool(args?.include_deleted, false);
+  const historyOnly = asBool(args?.history_only, false);
   // history_only implies include_history
-  const includeHistory = historyOnly ? true : (args?.include_history as boolean | undefined);
+  const includeHistory = historyOnly ? true : (typeof args?.include_history === "boolean" ? args.include_history : undefined);
 
   let historyFilters: HistoryFilters;
   try {
@@ -197,13 +226,27 @@ export async function handleSearchMemories(
     return errorResult(errorText(e));
   }
 
+  let dateFilters: { after?: Date; before?: Date };
+  try {
+    dateFilters = resolveDateFilters({
+      after: args?.after,
+      before: args?.before,
+      time_expr: args?.time_expr,
+    });
+  } catch (e) {
+    return errorResult(errorText(e));
+  }
+
   const results = await service.search(query, intent, {
     limit,
+    scope: asOptionalString(args?.scope),
     includeDeleted,
     includeHistory,
     historyOnly,
     historyFilters,
     offset,
+    after: dateFilters.after,
+    before: dateFilters.before,
   });
 
   if (results.length === 0) {
@@ -240,7 +283,11 @@ function formatMemoryDetail(
 }
 
 function formatSearchResult(r: SearchResult, includeDeleted: boolean): string {
-  let result = `[${r.source}] ID: ${r.id}\nContent: ${r.content}`;
+  let result = `[${r.source}] ID: ${r.id}\nConfidence: ${r.confidence.toFixed(2)}`;
+  if (r.project) {
+    result += `\nProject: ${r.project}`;
+  }
+  result += `\nContent: ${r.content}`;
   if (r.metadata && Object.keys(r.metadata).length > 0) {
     result += `\nMetadata: ${JSON.stringify(r.metadata)}`;
   }
@@ -305,25 +352,23 @@ export async function handleSetWaypoint(
   args: Record<string, unknown> | undefined,
   service: MemoryService
 ): Promise<CallToolResult> {
-  let project: string;
   let summary: string;
   try {
-    project = requireString(args, "project");
     summary = requireString(args, "summary");
   } catch (e) {
     return errorResult(errorText(e));
   }
 
   const memory = await service.setWaypoint({
-    project,
-    branch: args?.branch as string | undefined,
+    project: asOptionalString(args?.project),
+    branch: asOptionalString(args?.branch),
     summary,
-    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>) ?? {},
+    completed: args?.completed ? asArray(args.completed, "completed") : [],
+    in_progress_blocked: args?.in_progress_blocked ? asArray(args.in_progress_blocked, "in_progress_blocked") : [],
+    key_decisions: args?.key_decisions ? asArray(args.key_decisions, "key_decisions") : [],
+    next_steps: args?.next_steps ? asArray(args.next_steps, "next_steps") : [],
+    memory_ids: args?.memory_ids ? asArray(args.memory_ids, "memory_ids") : [],
+    metadata: asObject(args?.metadata),
   });
 
   return {
@@ -335,7 +380,7 @@ export async function handleGetWaypoint(
   args: Record<string, unknown> | undefined,
   service: MemoryService
 ): Promise<CallToolResult> {
-  const project = args?.project as string | undefined;
+  const project = asOptionalString(args?.project);
   const waypoint = await service.getLatestWaypoint(project);
 
   if (!waypoint) {
@@ -365,8 +410,8 @@ function parseHistoryFilters(
   args: Record<string, unknown> | undefined
 ): HistoryFilters {
   return {
-    sessionId: args?.session_id as string | undefined,
-    role: args?.role_filter as string | undefined,
+    sessionId: asOptionalString(args?.session_id),
+    role: asOptionalString(args?.role_filter),
     after: parseDate(args?.history_after, "history_after"),
     before: parseDate(args?.history_before, "history_before"),
   };
@@ -394,8 +439,8 @@ export async function handleIndexConversations(
   if ("error" in conv) return conv.error;
   const conversationService = conv.service;
 
-  const path = args?.path as string | undefined;
-  const sinceStr = args?.since as string | undefined;
+  const path = asOptionalString(args?.path);
+  const sinceStr = asOptionalString(args?.since);
   const since = sinceStr ? new Date(sinceStr) : undefined;
   if (since && isNaN(since.getTime())) {
     return errorResult("Invalid 'since' date format");
@@ -425,8 +470,8 @@ export async function handleListIndexedSessions(
   if ("error" in conv) return conv.error;
   const conversationService = conv.service;
 
-  const limit = (args?.limit as number) ?? 20;
-  const offset = (args?.offset as number) ?? 0;
+  const limit = asInt(args?.limit, 20, 1, 1000);
+  const offset = asInt(args?.offset, 0, 0, 10000);
   const { sessions, total } =
     await conversationService.listIndexedSessions(limit, offset);
 
@@ -464,7 +509,7 @@ export async function handleReindexSession(
   if ("error" in conv) return conv.error;
   const conversationService = conv.service;
 
-  const sessionId = args?.session_id as string | undefined;
+  const sessionId = asOptionalString(args?.session_id);
   if (!sessionId) {
     return errorResult("session_id is required");
   }

package/server/transports/mcp/tools.ts

@@ -47,6 +47,12 @@ For long content (>1000 chars), provide embedding_text with a searchable summary
               description: "Optional key-value metadata.",
               additionalProperties: true,
             },
+            project: {
+              type: "string",
+              description:
+                "Project to tag this memory with (canonical absolute path). " +
+                "Defaults to the current project — only pass this to file a memory under a different project.",
+            },
           },
           required: ["content"],
         },
@@ -139,7 +145,9 @@ INTENTS:
 - 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.`,
+When in doubt, search. Missing context is costlier than an extra query.
+
+SCOPE: Memories are stored globally across all projects. By default, search covers every project (results from the current project rank slightly higher and each result carries its project path). Pass scope: "project" when the query is clearly specific to the current repo — it cuts cross-project noise and scan cost.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -148,6 +156,14 @@ When in doubt, search. Missing context is costlier than an extra query.`,
         description:
           "Natural language search query. Include relevant keywords, project names, or technical terms.",
       },
+      scope: {
+        type: "string",
+        description:
+          'Project scope: "all" (default) searches every project with a ranking boost for the current one; ' +
+          '"project" restricts to the current project; or pass an explicit canonical project path ' +
+          '(e.g. "/home/user/Development/other-repo") to search that project only.',
+        default: "all",
+      },
       intent: {
         type: "string",
         enum: ["continuity", "fact_check", "frequent", "associative", "explore"],
@@ -201,6 +217,21 @@ When in doubt, search. Missing context is costlier than an extra query.`,
         type: "string",
         description: "Filter conversation history results before this ISO date.",
       },
+      after: {
+        type: "string",
+        description:
+          "Filter memories created after this ISO date (e.g. '2025-06-01'). Applies to both memories and conversation history.",
+      },
+      before: {
+        type: "string",
+        description:
+          "Filter memories created before this ISO date (e.g. '2026-01-01'). Applies to both memories and conversation history.",
+      },
+      time_expr: {
+        type: "string",
+        description:
+          "Natural relative time filter, resolved to 'after' date. Examples: 'past 7 days', 'last 2 weeks', 'past 3 hours'. Ignored if explicit 'after' is provided.",
+      },
     },
     required: ["query", "intent", "reason_for_search"],
   },
@@ -258,7 +289,11 @@ Retrievable via get_waypoint. Only one waypoint per project—new waypoints over
   inputSchema: {
     type: "object",
     properties: {
-      project: { type: "string", description: "Project name." },
+      project: {
+        type: "string",
+        description:
+          "Project to save the waypoint under. Defaults to the current project (detected from cwd) — usually omit this.",
+      },
       branch: { type: "string", description: "Branch name (optional)." },
       summary: { type: "string", description: "2-3 sentences: primary goal, current status." },
       completed: {
@@ -292,7 +327,7 @@ Retrievable via get_waypoint. Only one waypoint per project—new waypoints over
         additionalProperties: true,
       },
     },
-    required: ["project", "summary"],
+    required: ["summary"],
   },
 };
 
@@ -306,7 +341,8 @@ export const getWaypointTool: Tool = {
       project: {
         type: "string",
         description:
-          "Project name to retrieve waypoint for. If omitted, retrieves the default (legacy) waypoint.",
+          "Project to retrieve the waypoint for (canonical absolute path). " +
+          "Defaults to the current project — only pass this to read another project's waypoint.",
       },
     },
   },