@coreidentitylabs/open-graph-memory-mcp 1.0.1

package/src/tools/memory-tools.ts

@@ -0,0 +1,1067 @@
+// =============================================================================
+// MCP Tools — Agent-Driven Memory Operations
+// =============================================================================
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { v4 as uuidv4 } from "uuid";
+import type {
+  StorageBackend,
+  MemoryNode,
+  MemoryEdge,
+  NodeType,
+  ConsolidationStrategy,
+  LLMProvider,
+} from "../types.js";
+import { generateLocalEmbedding } from "../encoding/embedder.js";
+import { hybridSearch, getContextForTopic } from "../retrieval/search.js";
+import { consolidateMemory } from "../evolution/consolidator.js";
+import { encodeText } from "../encoding/pipeline.js";
+import {
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  CHARACTER_LIMIT,
+} from "../constants.js";
+
+// =============================================================================
+// Tool Registration
+// =============================================================================
+
+export function registerMemoryTools(
+  server: McpServer,
+  store: StorageBackend,
+  llm?: LLMProvider | null,
+): void {
+  // ---- WRITE TOOLS ----
+
+  registerAddEntities(server, store);
+  registerAddRelations(server, store);
+  registerSaveConversation(server, store);
+
+  // ---- READ TOOLS ----
+
+  registerSearch(server, store);
+  registerGetEntity(server, store);
+  registerListEntities(server, store);
+  registerGetRelations(server, store);
+  registerGetContext(server, store);
+
+  // ---- MANAGEMENT TOOLS ----
+
+  registerDeleteEntity(server, store);
+  registerConsolidate(server, store);
+  registerStatus(server, store);
+
+  // ---- OPTIONAL SERVER-SIDE ENCODING ----
+
+  if (llm) {
+    registerEncodeText(server, store, llm);
+    console.error(
+      `[open-memory] memory_encode_text tool enabled (LLM configured)`,
+    );
+  }
+}
+
+// =============================================================================
+// Write Tools
+// =============================================================================
+
+function registerAddEntities(server: McpServer, store: StorageBackend): void {
+  const EntitySchema = z.object({
+    name: z
+      .string()
+      .min(1)
+      .describe("Entity name (e.g., 'React Query', 'UserService')"),
+    type: z
+      .enum([
+        "entity",
+        "concept",
+        "event",
+        "code_pattern",
+        "decision",
+        "conversation",
+      ])
+      .default("entity")
+      .describe("Node type"),
+    description: z.string().min(1).describe("Description of the entity"),
+    metadata: z
+      .record(z.unknown())
+      .optional()
+      .describe("Optional key-value metadata"),
+  });
+
+  const InputSchema = z.object({
+    entities: z
+      .array(EntitySchema)
+      .min(1)
+      .max(50)
+      .describe("Array of entities to add to memory"),
+  });
+
+  server.registerTool(
+    "memory_add_entities",
+    {
+      title: "Add Entities to Memory",
+      description: `Store entities (people, tools, concepts, code patterns, decisions) in the memory graph.
+The agent extracts entities from conversation and passes structured data here.
+Server auto-generates embeddings for semantic search.
+
+Returns: IDs and names of stored entities.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        const results: { id: string; name: string; status: string }[] = [];
+
+        for (const entity of params.entities) {
+          // Check for existing entity by name
+          const existing = await store.getNodeByName(entity.name);
+          if (existing) {
+            // Update existing entity
+            await store.updateNode(existing.id, {
+              description: entity.description,
+              metadata: { ...existing.metadata, ...entity.metadata },
+              embedding: generateLocalEmbedding(
+                `${entity.name} ${entity.description}`,
+              ),
+            });
+            results.push({
+              id: existing.id,
+              name: entity.name,
+              status: "updated",
+            });
+          } else {
+            // Create new entity
+            const now = new Date().toISOString();
+            const node: MemoryNode = {
+              id: uuidv4(),
+              name: entity.name,
+              type: entity.type as NodeType,
+              description: entity.description,
+              embedding: generateLocalEmbedding(
+                `${entity.name} ${entity.description}`,
+              ),
+              metadata: entity.metadata ?? {},
+              createdAt: now,
+              updatedAt: now,
+              source: "agent",
+              accessCount: 0,
+            };
+            await store.addNode(node);
+            results.push({ id: node.id, name: entity.name, status: "created" });
+          }
+        }
+
+        const output = { stored: results.length, entities: results };
+        return {
+          content: [
+            { type: "text" as const, text: JSON.stringify(output, null, 2) },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerAddRelations(server: McpServer, store: StorageBackend): void {
+  const RelationSchema = z.object({
+    source: z.string().min(1).describe("Source entity name or ID"),
+    target: z.string().min(1).describe("Target entity name or ID"),
+    relation: z
+      .string()
+      .min(1)
+      .describe("Relationship type (e.g., 'uses', 'depends_on', 'decided_to')"),
+    description: z
+      .string()
+      .optional()
+      .describe("Description of the relationship"),
+    weight: z
+      .number()
+      .min(0)
+      .max(1)
+      .default(0.8)
+      .describe("Confidence weight (0-1)"),
+  });
+
+  const InputSchema = z.object({
+    relations: z
+      .array(RelationSchema)
+      .min(1)
+      .max(50)
+      .describe("Array of relationships to add"),
+  });
+
+  server.registerTool(
+    "memory_add_relations",
+    {
+      title: "Add Relations to Memory",
+      description: `Store relationships between entities in the memory graph.
+Source and target can be entity names (resolved automatically) or IDs.
+
+Returns: IDs and details of stored edges.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        const results: {
+          id: string;
+          source: string;
+          target: string;
+          relation: string;
+          status: string;
+        }[] = [];
+
+        for (const rel of params.relations) {
+          // Resolve source and target by name or ID
+          const sourceNode =
+            (await store.getNode(rel.source)) ??
+            (await store.getNodeByName(rel.source));
+          const targetNode =
+            (await store.getNode(rel.target)) ??
+            (await store.getNodeByName(rel.target));
+
+          if (!sourceNode) {
+            results.push({
+              id: "",
+              source: rel.source,
+              target: rel.target,
+              relation: rel.relation,
+              status: `error: source '${rel.source}' not found`,
+            });
+            continue;
+          }
+          if (!targetNode) {
+            results.push({
+              id: "",
+              source: rel.source,
+              target: rel.target,
+              relation: rel.relation,
+              status: `error: target '${rel.target}' not found`,
+            });
+            continue;
+          }
+
+          const now = new Date().toISOString();
+          const edge: MemoryEdge = {
+            id: uuidv4(),
+            source: sourceNode.id,
+            target: targetNode.id,
+            relation: rel.relation,
+            description:
+              rel.description ??
+              `${sourceNode.name} ${rel.relation} ${targetNode.name}`,
+            weight: rel.weight,
+            metadata: {},
+            createdAt: now,
+            updatedAt: now,
+          };
+
+          await store.addEdge(edge);
+          results.push({
+            id: edge.id,
+            source: sourceNode.name,
+            target: targetNode.name,
+            relation: rel.relation,
+            status: "created",
+          });
+        }
+
+        const output = {
+          stored: results.filter((r) => r.status === "created").length,
+          relations: results,
+        };
+        return {
+          content: [
+            { type: "text" as const, text: JSON.stringify(output, null, 2) },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerSaveConversation(
+  server: McpServer,
+  store: StorageBackend,
+): void {
+  const MessageSchema = z.object({
+    role: z.string().describe("Message role (user, assistant, system)"),
+    content: z.string().describe("Message content"),
+  });
+
+  const InputSchema = z.object({
+    messages: z
+      .array(MessageSchema)
+      .min(1)
+      .describe("Conversation messages to store"),
+    context: z
+      .string()
+      .optional()
+      .describe("Optional summary or context label for this conversation"),
+  });
+
+  server.registerTool(
+    "memory_save_conversation",
+    {
+      title: "Save Conversation to Memory",
+      description: `Store a conversation snapshot as an event node in the memory graph.
+Useful for preserving conversation history across sessions.
+
+Returns: ID of the stored conversation node.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        const now = new Date().toISOString();
+        const content = params.messages
+          .map((m) => `[${m.role}]: ${m.content}`)
+          .join("\n");
+        const summary = params.context ?? `Conversation at ${now}`;
+
+        const node: MemoryNode = {
+          id: uuidv4(),
+          name: summary,
+          type: "conversation",
+          description:
+            content.length > 2000
+              ? content.substring(0, 2000) + "..."
+              : content,
+          embedding: generateLocalEmbedding(
+            `${summary} ${content.substring(0, 500)}`,
+          ),
+          metadata: {
+            messageCount: params.messages.length,
+            fullContent: content,
+          },
+          createdAt: now,
+          updatedAt: now,
+          source: "conversation",
+          accessCount: 0,
+        };
+
+        await store.addNode(node);
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  id: node.id,
+                  name: node.name,
+                  messageCount: params.messages.length,
+                  status: "saved",
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+// =============================================================================
+// Read Tools
+// =============================================================================
+
+function registerSearch(server: McpServer, store: StorageBackend): void {
+  const InputSchema = z.object({
+    query: z.string().min(1).describe("Search query (natural language)"),
+    topK: z.number().int().min(1).max(50).default(10).describe("Max results"),
+    type: z
+      .enum([
+        "entity",
+        "concept",
+        "event",
+        "code_pattern",
+        "decision",
+        "conversation",
+      ])
+      .optional()
+      .describe("Filter by node type"),
+    timeRange: z
+      .object({
+        after: z
+          .string()
+          .optional()
+          .describe("ISO timestamp — only results after this"),
+        before: z
+          .string()
+          .optional()
+          .describe("ISO timestamp — only results before this"),
+      })
+      .optional()
+      .describe("Time range filter"),
+  });
+
+  server.registerTool(
+    "memory_search",
+    {
+      title: "Search Memory",
+      description: `Hybrid search across the memory graph: combines text matching, semantic similarity, and graph traversal.
+Returns entities, their scores, and related edges.
+
+Use this to find relevant context before making decisions or writing code.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        const results = await hybridSearch(store, {
+          query: params.query,
+          topK: params.topK,
+          type: params.type as NodeType | undefined,
+          timeRange: params.timeRange,
+        });
+
+        const output = {
+          totalMatches: results.totalNodes,
+          returnedCount: results.nodes.length,
+          results: results.nodes.map((r) => ({
+            id: r.node.id,
+            name: r.node.name,
+            type: r.node.type,
+            description: r.node.description,
+            score: Math.round(r.score * 1000) / 1000,
+            matchType: r.matchType,
+            updatedAt: r.node.updatedAt,
+          })),
+          relatedEdges: results.relatedEdges.slice(0, 20).map((e) => ({
+            source: e.source,
+            target: e.target,
+            relation: e.relation,
+            description: e.description,
+          })),
+        };
+
+        let text = JSON.stringify(output, null, 2);
+        if (text.length > CHARACTER_LIMIT) {
+          output.results = output.results.slice(0, 5);
+          output.relatedEdges = output.relatedEdges.slice(0, 5);
+          text = JSON.stringify({ ...output, truncated: true }, null, 2);
+        }
+
+        return {
+          content: [{ type: "text" as const, text }],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerGetEntity(server: McpServer, store: StorageBackend): void {
+  const InputSchema = z
+    .object({
+      name: z.string().optional().describe("Entity name to look up"),
+      id: z.string().optional().describe("Entity ID to look up"),
+    })
+    .refine((data) => data.name || data.id, {
+      message: "Either 'name' or 'id' must be provided",
+    });
+
+  server.registerTool(
+    "memory_get_entity",
+    {
+      title: "Get Entity Details",
+      description: `Get full details of a specific entity including all its relationships.
+Provide either entity name or ID.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        let node: MemoryNode | null = null;
+        if (params.id) {
+          node = await store.getNode(params.id);
+        } else if (params.name) {
+          node = await store.getNodeByName(params.name);
+        }
+
+        if (!node) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Entity not found: ${params.name ?? params.id}`,
+              },
+            ],
+          };
+        }
+
+        // Update access count
+        await store.updateNode(node.id, {
+          accessCount: node.accessCount + 1,
+          lastAccessedAt: new Date().toISOString(),
+        });
+
+        // Get relationships
+        const edges = await store.getEdgesForNode(node.id);
+
+        // Resolve edge node names
+        const edgeDetails = await Promise.all(
+          edges.map(async (e) => {
+            const otherNodeId = e.source === node!.id ? e.target : e.source;
+            const otherNode = await store.getNode(otherNodeId);
+            return {
+              relation: e.relation,
+              direction: e.source === node!.id ? "outgoing" : "incoming",
+              relatedEntity: otherNode?.name ?? otherNodeId,
+              relatedEntityType: otherNode?.type,
+              description: e.description,
+              weight: e.weight,
+            };
+          }),
+        );
+
+        const output = {
+          id: node.id,
+          name: node.name,
+          type: node.type,
+          description: node.description,
+          metadata: node.metadata,
+          createdAt: node.createdAt,
+          updatedAt: node.updatedAt,
+          validFrom: node.validFrom,
+          validUntil: node.validUntil,
+          accessCount: node.accessCount,
+          relationships: edgeDetails,
+        };
+
+        return {
+          content: [
+            { type: "text" as const, text: JSON.stringify(output, null, 2) },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerListEntities(server: McpServer, store: StorageBackend): void {
+  const InputSchema = z.object({
+    type: z
+      .enum([
+        "entity",
+        "concept",
+        "event",
+        "code_pattern",
+        "decision",
+        "conversation",
+      ])
+      .optional()
+      .describe("Filter by node type"),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_PAGE_SIZE)
+      .default(DEFAULT_PAGE_SIZE)
+      .describe("Max results per page"),
+    offset: z.number().int().min(0).default(0).describe("Pagination offset"),
+    nameContains: z.string().optional().describe("Filter by name substring"),
+  });
+
+  server.registerTool(
+    "memory_list_entities",
+    {
+      title: "List Memory Entities",
+      description: `List all entities in the memory graph with optional filtering and pagination.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        let results;
+        if (params.type || params.nameContains) {
+          const allMatches = await store.findNodes({
+            type: params.type as NodeType | undefined,
+            nameContains: params.nameContains,
+          });
+          results = {
+            nodes: allMatches.slice(
+              params.offset,
+              params.offset + params.limit,
+            ),
+            total: allMatches.length,
+          };
+        } else {
+          results = await store.getAllNodes(params.limit, params.offset);
+        }
+
+        const output = {
+          total: results.total,
+          count: results.nodes.length,
+          offset: params.offset,
+          entities: results.nodes.map((n) => ({
+            id: n.id,
+            name: n.name,
+            type: n.type,
+            description: n.description.substring(0, 200),
+            updatedAt: n.updatedAt,
+            accessCount: n.accessCount,
+          })),
+          hasMore: results.total > params.offset + results.nodes.length,
+          nextOffset:
+            results.total > params.offset + results.nodes.length
+              ? params.offset + results.nodes.length
+              : undefined,
+        };
+
+        return {
+          content: [
+            { type: "text" as const, text: JSON.stringify(output, null, 2) },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerGetRelations(server: McpServer, store: StorageBackend): void {
+  const InputSchema = z.object({
+    entity: z.string().min(1).describe("Entity name or ID"),
+    relation: z.string().optional().describe("Filter by relation type"),
+    direction: z
+      .enum(["in", "out", "both"])
+      .default("both")
+      .describe("Edge direction filter"),
+  });
+
+  server.registerTool(
+    "memory_get_relations",
+    {
+      title: "Get Entity Relations",
+      description: `Get all relationships for a given entity, optionally filtered by type and direction.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        const node =
+          (await store.getNode(params.entity)) ??
+          (await store.getNodeByName(params.entity));
+
+        if (!node) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Entity not found: ${params.entity}`,
+              },
+            ],
+          };
+        }
+
+        let edges = await store.getEdgesForNode(node.id, params.direction);
+
+        if (params.relation) {
+          edges = edges.filter((e) => e.relation === params.relation);
+        }
+
+        const edgeDetails = await Promise.all(
+          edges.map(async (e) => {
+            const otherNodeId = e.source === node.id ? e.target : e.source;
+            const otherNode = await store.getNode(otherNodeId);
+            return {
+              id: e.id,
+              relation: e.relation,
+              direction: e.source === node.id ? "outgoing" : "incoming",
+              relatedEntity: otherNode?.name ?? otherNodeId,
+              relatedEntityType: otherNode?.type,
+              description: e.description,
+              weight: e.weight,
+            };
+          }),
+        );
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  entity: node.name,
+                  totalRelations: edgeDetails.length,
+                  relations: edgeDetails,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerGetContext(server: McpServer, store: StorageBackend): void {
+  const InputSchema = z.object({
+    topic: z.string().min(1).describe("Topic to retrieve context for"),
+    maxTokens: z
+      .number()
+      .int()
+      .min(100)
+      .max(8000)
+      .default(2000)
+      .describe("Approximate max tokens in returned context"),
+  });
+
+  server.registerTool(
+    "memory_get_context",
+    {
+      title: "Get Context for Topic",
+      description: `Retrieve summarized context for a topic, formatted for direct injection into prompts.
+Use before making decisions or writing code to get historical context.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        const context = await getContextForTopic(
+          store,
+          params.topic,
+          params.maxTokens,
+        );
+
+        return {
+          content: [{ type: "text" as const, text: context }],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+// =============================================================================
+// Management Tools
+// =============================================================================
+
+function registerDeleteEntity(server: McpServer, store: StorageBackend): void {
+  const InputSchema = z
+    .object({
+      name: z.string().optional().describe("Entity name to delete"),
+      id: z.string().optional().describe("Entity ID to delete"),
+    })
+    .refine((data) => data.name || data.id, {
+      message: "Either 'name' or 'id' must be provided",
+    });
+
+  server.registerTool(
+    "memory_delete_entity",
+    {
+      title: "Delete Entity from Memory",
+      description: `Remove an entity and all its edges from the memory graph. This is destructive.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        let node = null;
+        if (params.id) node = await store.getNode(params.id);
+        else if (params.name) node = await store.getNodeByName(params.name);
+
+        if (!node) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Entity not found: ${params.name ?? params.id}`,
+              },
+            ],
+          };
+        }
+
+        const deleted = await store.deleteNode(node.id);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  deleted,
+                  id: node.id,
+                  name: node.name,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerConsolidate(server: McpServer, store: StorageBackend): void {
+  const InputSchema = z.object({
+    strategy: z
+      .enum(["full", "merge_only", "prune_only", "infer_only"])
+      .default("full")
+      .describe("Consolidation strategy"),
+  });
+
+  server.registerTool(
+    "memory_consolidate",
+    {
+      title: "Consolidate Memory",
+      description: `Run memory consolidation: merge duplicates, infer transitive edges, and prune stale nodes.else
+Strategies: full (all), merge_only, prune_only, infer_only.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        const result = await consolidateMemory(
+          store,
+          params.strategy as ConsolidationStrategy,
+        );
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                {
+                  ...result,
+                  durationMs: result.duration,
+                  status: "completed",
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+function registerStatus(server: McpServer, store: StorageBackend): void {
+  server.registerTool(
+    "memory_status",
+    {
+      title: "Memory Status",
+      description: `Get memory graph health: node/edge counts by type, storage backend, and last consolidation time.`,
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      try {
+        const stats = await store.getStats();
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(stats, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+// =============================================================================
+// Optional Server-Side Encoding Tool
+// =============================================================================
+
+function registerEncodeText(
+  server: McpServer,
+  store: StorageBackend,
+  llm: LLMProvider,
+): void {
+  const InputSchema = z.object({
+    text: z
+      .string()
+      .min(1)
+      .describe(
+        "Raw text to process (conversation excerpt, code comment, meeting notes, etc.)",
+      ),
+    autoStore: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Automatically store extracted entities and relations in memory (default: true)",
+      ),
+  });
+
+  server.registerTool(
+    "memory_encode_text",
+    {
+      title: "Encode Text (Server-Side LLM)",
+      description: `Extract entities and relationships from raw text using the server-side LLM.
+This is the automated alternative to manually calling memory_add_entities + memory_add_relations.
+Requires LLM_API_KEY to be configured.
+
+Pipeline: text → LLM extraction → entity resolution → embedding → storage
+
+Set autoStore=false to preview extraction results without saving.`,
+      inputSchema: InputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (params: z.infer<typeof InputSchema>) => {
+      try {
+        if (params.autoStore) {
+          // Full pipeline: extract + store
+          const result = await encodeText(params.text, store, llm);
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(
+                  {
+                    status: "encoded",
+                    entitiesCreated: result.entitiesCreated,
+                    entitiesUpdated: result.entitiesUpdated,
+                    relationsCreated: result.relationsCreated,
+                    details: result.details,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        } else {
+          // Preview mode: extract only, don't store
+          const { nodes: existingNodes } = await store.getAllNodes(10000, 0);
+          const existingNames = existingNodes.map((n) => n.name);
+          const extraction = await llm.extractEntitiesAndRelations(
+            params.text,
+            existingNames,
+          );
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify(
+                  {
+                    status: "preview",
+                    message:
+                      "Extraction preview — nothing stored. Set autoStore=true to save.",
+                    entities: extraction.entities,
+                    relations: extraction.relations,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        }
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  );
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function errorResponse(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text" as const,
+        text: `Error: ${message}`,
+      },
+    ],
+  };
+}