@utaba/deep-memory-local-mcp-server 0.16.0

package/dist/index.js

@@ -0,0 +1,2050 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync, existsSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// src/server/McpServer.ts
+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 {
+  DeepMemory,
+  InMemoryStorageProvider,
+  InMemorySearchProvider
+} from "@utaba/deep-memory";
+import { OpenAIEmbeddingProvider } from "@utaba/deep-memory-embeddings-openai";
+import { SqlServerStorageProvider } from "@utaba/deep-memory-storage-sqlserver";
+import { CosmosDbProvider } from "@utaba/deep-memory-storage-cosmosdb";
+
+// src/tools/base/BaseToolController.ts
+import { isValidUuid, EntityNotFoundError } from "@utaba/deep-memory";
+var BaseToolController = class {
+  constructor(context, logger2) {
+    this.context = context;
+    this.logger = logger2;
+  }
+  context;
+  logger;
+  async execute(params) {
+    try {
+      this.validateParams(params);
+      return await this.handleExecute(params);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.error(this.name, `Execution failed: ${message}`);
+      throw error;
+    }
+  }
+  validateParams(params) {
+    const schema = this.inputSchema;
+    const required = schema["required"];
+    if (required) {
+      for (const field of required) {
+        if (params[field] === void 0 || params[field] === null) {
+          throw new Error(`Required parameter '${field}' is missing`);
+        }
+      }
+    }
+  }
+  /**
+   * Resolve an entity identifier that may be either a GUID or a slug.
+   * Returns the GUID.
+   */
+  async resolveEntityId(repo, entityIdOrSlug) {
+    if (isValidUuid(entityIdOrSlug)) {
+      return entityIdOrSlug;
+    }
+    const entity = await repo.getBySlug(entityIdOrSlug);
+    if (!entity) {
+      throw new EntityNotFoundError(entityIdOrSlug);
+    }
+    return entity.id;
+  }
+};
+
+// src/tools/repository/CreateRepositoryTool.ts
+var CreateRepositoryTool = class extends BaseToolController {
+  get name() {
+    return "memory_create_repository";
+  }
+  get description() {
+    return "Create a new memory repository with an optional vocabulary definition and governance mode";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Unique identifier for the repository" },
+        label: { type: "string", description: "Human-readable name" },
+        description: { type: "string", description: "Purpose of this repository" },
+        type: { type: "string", description: "Repository type (optional classifier)" },
+        legal: { type: "string", description: "Legal or compliance notes for this repository" },
+        owner: { type: "string", description: "Owner of the repository (person, team, or org)" },
+        governanceMode: { type: "string", enum: ["locked", "managed", "open"], description: "Vocabulary governance mode (default: open)" },
+        defaultSimilarityThreshold: { type: "number", description: "Default similarity threshold for semantic search (0.0-1.0, default: 0.5). Lower for local embedding models, higher for OpenAI." },
+        metadata: {
+          type: "object",
+          description: "Extensible metadata object. Embedding model info (embeddingModelId, embeddingDimensions) is auto-detected from the configured provider if omitted."
+        },
+        vocabulary: {
+          type: "object",
+          description: "Initial vocabulary with entityTypes and relationshipTypes arrays",
+          properties: {
+            entityTypes: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  type: { type: "string" },
+                  description: { type: "string" },
+                  properties: { type: "array", items: { type: "object" } }
+                },
+                required: ["type", "description"]
+              }
+            },
+            relationshipTypes: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  type: { type: "string" },
+                  description: { type: "string" },
+                  allowedSourceTypes: { type: "array", items: { type: "string" } },
+                  allowedTargetTypes: { type: "array", items: { type: "string" } },
+                  bidirectional: { type: "boolean" },
+                  properties: { type: "array", items: { type: "object" } }
+                },
+                required: ["type", "description", "allowedSourceTypes", "allowedTargetTypes"]
+              }
+            }
+          }
+        }
+      },
+      required: ["repositoryId", "label"]
+    };
+  }
+  async handleExecute(params) {
+    const mode = params["governanceMode"] ?? "open";
+    const repo = await this.context.deepMemory.createRepository({
+      repositoryId: params["repositoryId"],
+      label: params["label"],
+      description: params["description"],
+      type: params["type"],
+      legal: params["legal"],
+      owner: params["owner"],
+      vocabulary: params["vocabulary"],
+      governance: {
+        mode,
+        defaultSimilarityThreshold: params["defaultSimilarityThreshold"]
+      },
+      metadata: params["metadata"]
+    });
+    return { repositoryId: repo.repositoryId, message: `Repository '${params["label"]}' created` };
+  }
+};
+
+// src/tools/repository/OpenRepositoryTool.ts
+var OpenRepositoryTool = class _OpenRepositoryTool extends BaseToolController {
+  get name() {
+    return "memory_open_repository";
+  }
+  get description() {
+    return "Open a memory repository by ID or label. Call this first before any entity, relationship, or graph operations. Returns vocabulary and stats.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "ID of the repository to open" },
+        label: { type: "string", description: "Repository label \u2014 use as alternative to repositoryId" }
+      },
+      required: []
+    };
+  }
+  async handleExecute(params) {
+    const repositoryId = params["repositoryId"];
+    const label = params["label"];
+    if (!repositoryId && !label) {
+      throw new Error("Provide either repositoryId or label");
+    }
+    let resolvedId;
+    if (repositoryId) {
+      resolvedId = repositoryId;
+    } else {
+      const allRepos = await this.context.deepMemory.listRepositories();
+      const matches = allRepos.items.filter(
+        (r) => r.label.toLowerCase() === label.toLowerCase()
+      );
+      if (matches.length === 0) {
+        throw new Error(`No repository found with label '${label}'`);
+      }
+      if (matches.length > 1) {
+        return {
+          error: "ambiguous_label",
+          message: `Multiple repositories match label '${label}'. Provide a repositoryId.`,
+          candidates: matches.map((r) => ({ repositoryId: r.repositoryId, label: r.label }))
+        };
+      }
+      resolvedId = matches[0].repositoryId;
+    }
+    const repo = await this.context.getRepository(resolvedId);
+    const [vocabulary, stats] = await Promise.all([
+      repo.getVocabulary(),
+      repo.getStats()
+    ]);
+    return {
+      repositoryId: repo.repositoryId,
+      message: `Repository '${resolvedId}' opened`,
+      vocabulary: _OpenRepositoryTool.stripAuditFields(vocabulary),
+      stats,
+      agentInstructions: repo.getQueryGuide()
+    };
+  }
+  /** Strip audit/versioning fields from vocabulary to reduce response size for AI consumers */
+  static stripAuditFields(resolved) {
+    const { vocabulary, governanceMode, governanceConfig } = resolved;
+    return {
+      governanceMode,
+      governanceConfig,
+      entityTypes: vocabulary.entityTypes.map(({ type, description, properties }) => ({
+        type,
+        description,
+        properties
+      })),
+      relationshipTypes: vocabulary.relationshipTypes.map(({ type, description, allowedSourceTypes, allowedTargetTypes, bidirectional, properties }) => ({
+        type,
+        description,
+        allowedSourceTypes,
+        allowedTargetTypes,
+        bidirectional,
+        ...properties?.length ? { properties } : {}
+      }))
+    };
+  }
+};
+
+// src/tools/repository/ListRepositoriesTool.ts
+var ListRepositoriesTool = class extends BaseToolController {
+  get name() {
+    return "memory_list_repositories";
+  }
+  get description() {
+    return "List all available memory repositories";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "Filter by repository type" },
+        limit: { type: "number", description: "Max results (default 20)" },
+        offset: { type: "number", description: "Pagination offset (default 0)" }
+      }
+    };
+  }
+  async handleExecute(params) {
+    const filter = {};
+    if (params["type"]) filter["type"] = params["type"];
+    filter["limit"] = params["limit"] ?? 20;
+    filter["offset"] = params["offset"] ?? 0;
+    return this.context.deepMemory.listRepositories(filter);
+  }
+};
+
+// src/tools/repository/UpdateRepositoryTool.ts
+var UpdateRepositoryTool = class extends BaseToolController {
+  get name() {
+    return "memory_update_repository";
+  }
+  get description() {
+    return "Update repository metadata and settings \u2014 label, description, governance mode, similarity threshold, etc.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to update" },
+        label: { type: "string", description: "New label" },
+        description: { type: "string", description: "New description" },
+        type: { type: "string", description: "New repository type" },
+        owner: { type: "string", description: "New owner" },
+        governanceMode: { type: "string", enum: ["locked", "managed", "open"], description: "New governance mode" },
+        defaultSimilarityThreshold: { type: "number", description: "Default similarity threshold for semantic search (0.0-1.0). Model-dependent \u2014 lower for local models, higher for OpenAI." },
+        requireApproval: { type: "boolean", description: "Managed mode: if true, all vocabulary proposals queue for human approval" },
+        deduplicationEnabled: { type: "boolean", description: "Open mode: whether vocabulary deduplication is enforced (default true)" },
+        autoApproveThreshold: { type: "number", description: "Managed mode: similarity score below which vocabulary proposals auto-approve (default 0.3)" },
+        metadata: { type: "object", description: 'Metadata updates (shallow-merged with existing). E.g. { "embeddingModelId": "...", "embeddingDimensions": 4096 }' }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repositoryId = params["repositoryId"];
+    const governanceMode = params["governanceMode"];
+    const defaultSimilarityThreshold = params["defaultSimilarityThreshold"];
+    const requireApproval = params["requireApproval"];
+    const deduplicationEnabled = params["deduplicationEnabled"];
+    const autoApproveThreshold = params["autoApproveThreshold"];
+    const hasGovernanceUpdate = governanceMode !== void 0 || defaultSimilarityThreshold !== void 0 || requireApproval !== void 0 || deduplicationEnabled !== void 0 || autoApproveThreshold !== void 0;
+    let governanceConfig;
+    if (hasGovernanceUpdate) {
+      const repo = await this.context.getRepository(repositoryId);
+      const current = (await repo.getVocabulary()).governanceConfig;
+      governanceConfig = {
+        ...current,
+        ...governanceMode !== void 0 ? { mode: governanceMode } : {},
+        ...defaultSimilarityThreshold !== void 0 ? { defaultSimilarityThreshold } : {},
+        ...requireApproval !== void 0 ? { requireApproval } : {},
+        ...deduplicationEnabled !== void 0 ? { deduplicationEnabled } : {},
+        ...autoApproveThreshold !== void 0 ? { autoApproveThreshold } : {}
+      };
+    }
+    const updated = await this.context.deepMemory.updateRepository(repositoryId, {
+      label: params["label"],
+      description: params["description"],
+      type: params["type"],
+      owner: params["owner"],
+      governanceConfig,
+      metadata: params["metadata"]
+    });
+    this.context.evictRepository(repositoryId);
+    return { repositoryId: updated.repositoryId, message: `Repository '${updated.label}' updated` };
+  }
+};
+
+// src/tools/repository/DeleteRepositoryTool.ts
+var DeleteRepositoryTool = class extends BaseToolController {
+  get name() {
+    return "memory_delete_repository";
+  }
+  get description() {
+    return "Delete a memory repository and all its data permanently. Use deleteContentsOnly to remove all entities and relationships while keeping the repository and vocabulary intact.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "ID of the repository to delete" },
+        deleteContentsOnly: { type: "boolean", description: "When true, only delete entities and relationships \u2014 the repository and vocabulary are preserved. Defaults to false." }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repositoryId = params["repositoryId"];
+    const deleteContentsOnly = params["deleteContentsOnly"] === true;
+    if (deleteContentsOnly) {
+      const result = await this.context.deepMemory.deleteAllContents(repositoryId);
+      this.context.evictRepository(repositoryId);
+      return {
+        message: `Repository '${repositoryId}' contents deleted (${result.deletedEntities} entities, ${result.deletedRelationships} relationships removed). Repository and vocabulary preserved.`,
+        deletedEntities: result.deletedEntities,
+        deletedRelationships: result.deletedRelationships
+      };
+    }
+    await this.context.deepMemory.deleteRepository(repositoryId);
+    this.context.evictRepository(repositoryId);
+    return { message: `Repository '${repositoryId}' deleted` };
+  }
+};
+
+// src/tools/repository/EnsureSchemaTool.ts
+var EnsureSchemaTool = class extends BaseToolController {
+  get name() {
+    return "memory_ensure_schema";
+  }
+  get description() {
+    return "Ensure the storage provider schema exists (creates tables/indexes if needed). Idempotent \u2014 safe to call multiple times. Only relevant for persistent storage providers (e.g., SQL Server); no-op for in-memory storage.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {}
+    };
+  }
+  async handleExecute(_params) {
+    const result = await this.context.deepMemory.ensureSchema();
+    return { success: true, ...result };
+  }
+};
+
+// src/tools/repository/ValidateEntitiesTool.ts
+var ValidateEntitiesTool = class extends BaseToolController {
+  get name() {
+    return "memory_validate_entities";
+  }
+  get description() {
+    return "Audit entities in the repository against the current vocabulary. Paging is issue-based: `take` caps how many issues are returned, `offset` skips that many issues. Typical workflow: call with offset=0, fix the returned issues, call again with offset=0. `offset` is only for inspecting a later slice without mutating. Loop until `done` is true. Returns issues fixable with memory_update_entity. Use memory_validate_relationships for relationships.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to validate" },
+        offset: { type: "number", description: "Number of issues to skip before returning (default 0). The normal fix-and-retry workflow always uses 0; pass nextOffset only to inspect a later slice without fixing." },
+        take: { type: "number", description: "Maximum issues to return in this call (default 200)" },
+        delayBetweenChunksMs: { type: "number", description: "Pause between export chunks for manual rate limiting (default 0)" }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    return repo.validateEntities({
+      offset: params["offset"],
+      take: params["take"],
+      delayBetweenChunksMs: params["delayBetweenChunksMs"]
+    });
+  }
+};
+
+// src/tools/repository/ValidateRelationshipsTool.ts
+var ValidateRelationshipsTool = class extends BaseToolController {
+  get name() {
+    return "memory_validate_relationships";
+  }
+  get description() {
+    return "Audit relationships in the repository against the current vocabulary. Paging is issue-based: `take` caps how many issues are returned, `offset` skips that many issues. Typical workflow: call with offset=0, fix the returned issues, call again with offset=0. `offset` is only for inspecting a later slice without mutating. Loop until `done` is true. The full entity set is loaded once per call to resolve orphan and type-mismatch checks. Returns issues fixable with memory_remove_relationships / memory_create_relationships.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to validate" },
+        offset: { type: "number", description: "Number of issues to skip before returning (default 0). The normal fix-and-retry workflow always uses 0; pass nextOffset only to inspect a later slice without fixing." },
+        take: { type: "number", description: "Maximum issues to return in this call (default 200)" },
+        delayBetweenChunksMs: { type: "number", description: "Pause between export chunks for manual rate limiting (default 0)" }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    return repo.validateRelationships({
+      offset: params["offset"],
+      take: params["take"],
+      delayBetweenChunksMs: params["delayBetweenChunksMs"]
+    });
+  }
+};
+
+// src/tools/entity/CreateEntitiesTool.ts
+var CreateEntitiesTool = class extends BaseToolController {
+  get name() {
+    return "memory_create_entities";
+  }
+  get description() {
+    return "Create one or more entities (nodes) in a repository. Entity types and properties must match the repository vocabulary \u2014 call memory_open_repository first to see valid types.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to create the entities in" },
+        entities: {
+          type: "array",
+          description: "Array of entities to create",
+          items: {
+            type: "object",
+            properties: {
+              entityType: { type: "string", description: "Entity type (must exist in vocabulary)" },
+              label: { type: "string", description: "Human-readable label" },
+              summary: { type: "string", description: "Brief description of the entity" },
+              properties: { type: "object", description: "Typed properties per vocabulary schema" },
+              data: { type: "string", description: "Raw content/data for the entity" },
+              dataFormat: { type: "string", description: "Format of the data field (e.g. text/plain, text/markdown)" }
+            },
+            required: ["entityType", "label"]
+          },
+          minItems: 1
+        }
+      },
+      required: ["repositoryId", "entities"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const entities = params["entities"];
+    return repo.createEntities(entities.map((e) => ({
+      entityType: e.entityType,
+      label: e.label,
+      summary: e.summary,
+      properties: e.properties,
+      data: e.data,
+      dataFormat: e.dataFormat
+    })));
+  }
+};
+
+// src/tools/entity/UpdateEntityTool.ts
+var UpdateEntityTool = class extends BaseToolController {
+  get name() {
+    return "memory_update_entity";
+  }
+  get description() {
+    return "Update an existing entity \u2014 entityType, label, summary, properties, or data. Accepts entity ID (GUID) or slug. Changing entityType must be valid in the vocabulary and regenerates the slug with the new type prefix. To clear an optional field, pass null: summary/data/dataFormat set to null are cleared, and property values set to null are removed from the entity (RFC 7396 JSON Merge Patch). Omitting a field leaves it unchanged.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entity" },
+        entityId: { type: "string", description: "Entity ID (GUID) or slug" },
+        entityType: { type: "string", description: "New entity type \u2014 must exist in the vocabulary. Regenerates the slug and re-validates properties against the new type." },
+        label: { type: "string", description: "New label" },
+        summary: { type: ["string", "null"], description: "New summary. Pass null to clear the existing summary." },
+        properties: { type: "object", description: "Properties to merge with existing. Property values set to null are removed from the entity (RFC 7396 JSON Merge Patch semantics)." },
+        data: { type: ["string", "null"], description: "New raw content/data. Pass null to clear." },
+        dataFormat: { type: ["string", "null"], description: "Format of the data field. Pass null to clear." },
+        reembed: { type: "boolean", description: "Force regeneration of the embedding vector (e.g. after switching embedding models)" }
+      },
+      required: ["repositoryId", "entityId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const resolvedId = await this.resolveEntityId(repo, params["entityId"]);
+    const updates = {};
+    if (params["entityType"] !== void 0) updates["entityType"] = params["entityType"];
+    if (params["label"] !== void 0) updates["label"] = params["label"];
+    if (params["summary"] !== void 0) updates["summary"] = params["summary"];
+    if (params["properties"] !== void 0) updates["properties"] = params["properties"];
+    if (params["data"] !== void 0) updates["data"] = params["data"];
+    if (params["dataFormat"] !== void 0) updates["dataFormat"] = params["dataFormat"];
+    if (params["reembed"] !== void 0) updates["reembed"] = params["reembed"];
+    return repo.updateEntity(resolvedId, updates);
+  }
+};
+
+// src/tools/base/stripProvenance.ts
+function stripProvenance(obj) {
+  const { provenance, ...rest } = obj;
+  return rest;
+}
+function stripProvenanceArray(items) {
+  return items.map(stripProvenance);
+}
+
+// src/tools/entity/GetEntityTool.ts
+var GetEntityTool = class extends BaseToolController {
+  get name() {
+    return "memory_get_entity";
+  }
+  get description() {
+    return "Retrieve a single entity by ID (GUID) or slug with configurable detail level (brief, summary, or full)";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entity" },
+        entityId: { type: "string", description: 'Entity ID (GUID) or slug (e.g. "person:john-smith")' },
+        detailLevel: { type: "string", enum: ["brief", "summary", "full"], description: "Level of detail (default: full)" }
+      },
+      required: ["repositoryId", "entityId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const resolvedId = await this.resolveEntityId(repo, params["entityId"]);
+    const detailLevel = params["detailLevel"] ?? "full";
+    const entity = await repo.getEntity(resolvedId, detailLevel);
+    if (!entity) {
+      throw new Error(`Entity '${params["entityId"]}' not found`);
+    }
+    return detailLevel === "full" ? stripProvenance(entity) : entity;
+  }
+};
+
+// src/tools/base/provenanceHelper.ts
+function buildProvenanceFilter(params) {
+  const conversationId = params["conversationId"];
+  const actor = params["actor"];
+  const dateRange = params["dateRange"];
+  if (!conversationId && !actor && !dateRange) return void 0;
+  return {
+    conversationIds: conversationId ? [conversationId] : void 0,
+    actors: actor ? [actor] : void 0,
+    dateRange
+  };
+}
+
+// src/tools/entity/FindEntitiesTool.ts
+var FindEntitiesTool = class extends BaseToolController {
+  get name() {
+    return "memory_find_entities";
+  }
+  get description() {
+    return "Search for entities by label, type, or properties with pagination. Requires a repository to be opened first via memory_open_repository.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to search in" },
+        searchTerm: { type: "string", description: "Search term to match against entity labels" },
+        entityType: { type: "string", description: "Filter by a single entity type (convenience alias for entityTypes)" },
+        entityTypes: { type: "array", items: { type: "string" }, description: "Filter by entity type(s)" },
+        properties: { type: "object", description: "Filter by property values" },
+        limit: { type: "number", description: "Max results (default 10, max 50)" },
+        offset: { type: "number", description: "Pagination offset" },
+        detailLevel: { type: "string", enum: ["brief", "summary", "full"], description: "Detail level for returned entities (default: summary)" },
+        conversationId: { type: "string", description: "Filter to entities from this conversation" },
+        actor: { type: "string", description: "Filter to entities created/modified by this actor" },
+        dateRange: { type: "object", properties: { from: { type: "string" }, to: { type: "string" } }, description: "Filter by date range (ISO 8601)" },
+        includeRelationshipSummary: { type: "boolean", description: "Attach a relationship count summary (outbound/inbound by type) to each entity (default false)" }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    let entityTypes = params["entityTypes"];
+    if (!entityTypes && params["entityType"]) {
+      entityTypes = [params["entityType"]];
+    }
+    let result = await repo.findEntities({
+      searchTerm: params["searchTerm"],
+      entityTypes,
+      properties: params["properties"],
+      limit: params["limit"],
+      offset: params["offset"],
+      detailLevel: params["detailLevel"],
+      provenance: buildProvenanceFilter(params)
+    });
+    if (params["detailLevel"] === "full") {
+      result = { ...result, items: stripProvenanceArray(result.items) };
+    }
+    if (!params["includeRelationshipSummary"]) {
+      return result;
+    }
+    const itemsWithSummary = await Promise.all(
+      result.items.map(async (entity) => {
+        const relationshipSummary = await repo.getRelationshipSummary(entity.id);
+        return { ...entity, relationshipSummary };
+      })
+    );
+    return { ...result, items: itemsWithSummary };
+  }
+};
+
+// src/tools/entity/DeleteEntitiesTool.ts
+var DeleteEntitiesTool = class extends BaseToolController {
+  get name() {
+    return "memory_delete_entities";
+  }
+  get description() {
+    return "Delete one or more entities and their associated relationships from the knowledge graph in a single batch operation. Accepts entity IDs (GUIDs) or slugs.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entities" },
+        entityIds: {
+          type: "array",
+          description: "Entity IDs (GUIDs or slugs) to delete",
+          items: { type: "string" },
+          minItems: 1
+        }
+      },
+      required: ["repositoryId", "entityIds"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const rawIds = params["entityIds"];
+    const resolvedIds = await Promise.all(rawIds.map((id) => this.resolveEntityId(repo, id)));
+    return repo.deleteEntities(resolvedIds);
+  }
+};
+
+// src/tools/entity/ReembedRepositoryTool.ts
+var ReembedRepositoryTool = class extends BaseToolController {
+  get name() {
+    return "memory_reembed_repository";
+  }
+  get description() {
+    return "Re-embed all entities in a repository. Optionally switch to a different embedding model or dimensionality \u2014 the repository metadata is updated first so subsequent writes use the new configuration. Retries failed batches with exponential backoff. Aborts early if error threshold is reached.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to re-embed" },
+        model: { type: "string", description: 'New embedding model identifier to switch the repository to (e.g. "Qwen/Qwen3-Embedding-8B"). Omit to keep the current model.' },
+        dimensions: { type: "number", description: "New embedding dimensionality to switch the repository to (e.g. 1024). Omit to keep the current dimensionality." },
+        batchSize: { type: "number", description: "Entities per batch (default 50, max 200)" },
+        maxRetries: { type: "number", description: "Retries per batch on embedding API failure with exponential backoff (default 3)" },
+        errorThresholdToAbort: { type: "number", description: "Abort after this many cumulative failures. Omit for no limit." },
+        delayBetweenBatchesMs: { type: "number", description: "Milliseconds to wait between batches for rate limiting (default 0)" }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repositoryId = params["repositoryId"];
+    const batchSize = Math.min(params["batchSize"] ?? 50, 200);
+    const result = await this.context.deepMemory.reembedAll(repositoryId, {
+      model: params["model"],
+      dimensions: params["dimensions"],
+      batchSize,
+      maxRetries: params["maxRetries"],
+      errorThresholdToAbort: params["errorThresholdToAbort"],
+      delayBetweenBatchesMs: params["delayBetweenBatchesMs"]
+    });
+    return {
+      processed: result.processed,
+      failed: result.failed,
+      errors: result.errors,
+      modelId: result.modelId,
+      dimensions: result.dimensions
+    };
+  }
+};
+
+// src/tools/relationship/CreateRelationshipsTool.ts
+var CreateRelationshipsTool = class extends BaseToolController {
+  get name() {
+    return "memory_create_relationships";
+  }
+  get description() {
+    return "Create one or more relationships (edges) between entities. Relationship types must be in the vocabulary. Entity references accept either GUID or slug.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entities" },
+        relationships: {
+          type: "array",
+          description: "Array of relationships to create",
+          items: {
+            type: "object",
+            properties: {
+              relationshipType: { type: "string", description: "Relationship type (must exist in vocabulary)" },
+              sourceEntityId: { type: "string", description: "Source entity ID (GUID) or slug" },
+              targetEntityId: { type: "string", description: "Target entity ID (GUID) or slug" },
+              properties: { type: "object", description: "Typed properties per vocabulary schema" }
+            },
+            required: ["relationshipType", "sourceEntityId", "targetEntityId"]
+          },
+          minItems: 1
+        }
+      },
+      required: ["repositoryId", "relationships"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const relationships = params["relationships"];
+    const resolved = await Promise.all(
+      relationships.map(async (r) => ({
+        relationshipType: r.relationshipType,
+        sourceEntityId: await this.resolveEntityId(repo, r.sourceEntityId),
+        targetEntityId: await this.resolveEntityId(repo, r.targetEntityId),
+        properties: r.properties
+      }))
+    );
+    return repo.createRelationships(resolved);
+  }
+};
+
+// src/tools/relationship/RemoveRelationshipsTool.ts
+var RemoveRelationshipsTool = class extends BaseToolController {
+  get name() {
+    return "memory_remove_relationships";
+  }
+  get description() {
+    return "Remove one or more relationships (edges) from the knowledge graph in a single batch operation";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the relationships" },
+        relationshipIds: {
+          type: "array",
+          description: "IDs of relationships to remove",
+          items: { type: "string" },
+          minItems: 1
+        }
+      },
+      required: ["repositoryId", "relationshipIds"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    return repo.removeRelationships(params["relationshipIds"]);
+  }
+};
+
+// src/tools/relationship/GetRelationshipsTool.ts
+var GetRelationshipsTool = class extends BaseToolController {
+  get name() {
+    return "memory_get_relationships";
+  }
+  get description() {
+    return "Get all relationships for a given entity, with optional type and direction filters. Accepts entity ID (GUID) or slug.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entity" },
+        entityId: { type: "string", description: "Entity ID (GUID) or slug" },
+        relationshipTypes: { type: "array", items: { type: "string" }, description: "Filter by relationship type(s)" },
+        direction: { type: "string", enum: ["outbound", "inbound", "both"], description: "Direction filter (default: both)" },
+        limit: { type: "number", description: "Max results (default 20, max 100)" },
+        offset: { type: "number", description: "Pagination offset (default 0)" },
+        propertyFilters: { type: "array", items: { type: "object", properties: { key: { type: "string" }, operator: { type: "string", enum: ["eq", "neq", "isNull", "isNotNull", "gt", "lt", "gte", "lte", "contains"] }, value: {} }, required: ["key", "operator"] }, description: "Filter by relationship property values (AND)" }
+      },
+      required: ["repositoryId", "entityId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const resolvedId = await this.resolveEntityId(repo, params["entityId"]);
+    const rawLimit = params["limit"];
+    const limit = Math.min(rawLimit ?? 20, 100);
+    const result = await repo.getRelationships(resolvedId, {
+      relationshipTypes: params["relationshipTypes"],
+      direction: params["direction"],
+      limit,
+      offset: params["offset"] ?? 0,
+      propertyFilters: params["propertyFilters"]
+    });
+    return { ...result, items: stripProvenanceArray(result.items) };
+  }
+};
+
+// src/tools/graph/ExploreNeighborhoodTool.ts
+var ExploreNeighborhoodTool = class extends BaseToolController {
+  get name() {
+    return "memory_explore_neighborhood";
+  }
+  get description() {
+    return "Explore the neighborhood of an entity using BFS traversal (depth 1-3). Accepts entity ID (GUID) or slug.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entity" },
+        entityId: { type: "string", description: "Starting entity ID (GUID) or slug" },
+        depth: { type: "number", enum: [1, 2, 3], description: "Exploration depth (default: 1)" },
+        relationshipTypes: { type: "array", items: { type: "string" }, description: "Filter by relationship type(s)" },
+        entityTypes: { type: "array", items: { type: "string" }, description: "Filter result entity types" },
+        direction: { type: "string", enum: ["outbound", "inbound", "both"], description: "Direction filter (default: both)" },
+        limitPerType: { type: "number", description: "Max entities per relationship type (default 10, max 50)" },
+        offsetPerType: { type: "number", description: "Pagination offset per relationship type (default 0)" },
+        detailLevel: { type: "string", enum: ["brief", "summary", "full"], description: "Detail level for returned entities (default: summary)" },
+        relationshipPropertyFilters: { type: "array", items: { type: "object", properties: { key: { type: "string" }, operator: { type: "string", enum: ["eq", "neq", "isNull", "isNotNull", "gt", "lt", "gte", "lte", "contains"] }, value: {} }, required: ["key", "operator"] }, description: "Filter relationships by property values (AND)" }
+      },
+      required: ["repositoryId", "entityId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const resolvedId = await this.resolveEntityId(repo, params["entityId"]);
+    const rawLimitPerType = params["limitPerType"];
+    const limitPerType = Math.min(rawLimitPerType ?? 10, 50);
+    const detailLevel = params["detailLevel"];
+    const result = await repo.exploreNeighborhood(resolvedId, {
+      depth: params["depth"],
+      relationshipTypes: params["relationshipTypes"],
+      entityTypes: params["entityTypes"],
+      direction: params["direction"],
+      limitPerType,
+      offsetPerType: params["offsetPerType"] ?? 0,
+      detailLevel,
+      relationshipPropertyFilters: params["relationshipPropertyFilters"]
+    });
+    if (detailLevel === "full") {
+      result.center = stripProvenance(result.center);
+      for (const layer of result.layers) {
+        for (const key of Object.keys(layer)) {
+          const bucket = layer[key];
+          if (bucket && typeof bucket === "object" && "entities" in bucket) {
+            const b = bucket;
+            b.entities = stripProvenanceArray(b.entities);
+          }
+        }
+      }
+    }
+    return result;
+  }
+};
+
+// src/tools/graph/FindPathsTool.ts
+var FindPathsTool = class extends BaseToolController {
+  get name() {
+    return "memory_find_paths";
+  }
+  get description() {
+    return "Find paths between two entities in the knowledge graph. Accepts entity IDs (GUID) or slugs.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entities" },
+        sourceEntityId: { type: "string", description: "Starting entity ID (GUID) or slug" },
+        targetEntityId: { type: "string", description: "Destination entity ID (GUID) or slug" },
+        maxDepth: { type: "number", description: "Maximum path depth (default: 3, max: 5)" },
+        relationshipTypes: { type: "array", items: { type: "string" }, description: "Filter allowed relationship types" },
+        entityTypes: { type: "array", items: { type: "string" }, description: "Filter entities in paths by type(s)" },
+        limit: { type: "number", description: "Maximum number of paths to return (default: 5)" },
+        offset: { type: "number", description: "Pagination offset (default: 0)" },
+        detailLevel: { type: "string", enum: ["brief", "summary", "full"], description: "Detail level for returned entities (default: brief)" },
+        relationshipPropertyFilters: { type: "array", items: { type: "object", properties: { key: { type: "string" }, operator: { type: "string", enum: ["eq", "neq", "isNull", "isNotNull", "gt", "lt", "gte", "lte", "contains"] }, value: {} }, required: ["key", "operator"] }, description: "Filter relationships by property values (AND)" }
+      },
+      required: ["repositoryId", "sourceEntityId", "targetEntityId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const sourceId = await this.resolveEntityId(repo, params["sourceEntityId"]);
+    const targetId = await this.resolveEntityId(repo, params["targetEntityId"]);
+    const detailLevel = params["detailLevel"];
+    const result = await repo.findPaths(sourceId, targetId, {
+      maxDepth: params["maxDepth"],
+      relationshipTypes: params["relationshipTypes"],
+      entityTypes: params["entityTypes"],
+      limit: params["limit"],
+      offset: params["offset"],
+      detailLevel,
+      relationshipPropertyFilters: params["relationshipPropertyFilters"]
+    });
+    if (detailLevel === "full") {
+      for (const path of result.paths) {
+        path.entities = stripProvenanceArray(path.entities);
+        path.relationships = path.relationships.map((r) => stripProvenance(r));
+      }
+    } else {
+      for (const path of result.paths) {
+        path.relationships = path.relationships.map((r) => stripProvenance(r));
+      }
+    }
+    return result;
+  }
+};
+
+// src/tools/graph/GetGraphTool.ts
+var PAGE_SIZE = 200;
+var GetGraphTool = class extends BaseToolController {
+  get name() {
+    return "memory_get_graph";
+  }
+  get description() {
+    return "Get the knowledge graph for a repository \u2014 entities, relationships, vocabulary, and stats. Returns up to 200 entities per page with a cursor for continuation. For large repositories, prefer memory_query_graph, memory_find_entities with filters and memory_explore_neighborhood for targeted exploration.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to get the graph for" },
+        cursor: { type: "string", description: "Opaque cursor from a previous response to fetch the next page" },
+        detailLevel: { type: "string", enum: ["brief", "summary", "full"], description: "Detail level for returned entities (default: summary)" }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repositoryId = params["repositoryId"];
+    const cursor = params["cursor"];
+    const repo = await this.context.getRepository(repositoryId);
+    const offset = cursor ? parseInt(cursor.split(":")[1], 10) : 0;
+    const detailLevel = params["detailLevel"];
+    const result = await repo.getGraph({ limit: PAGE_SIZE, offset, detailLevel });
+    result.relationships = result.relationships.map(
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      ({ provenance, ...rest }) => rest
+    );
+    return result;
+  }
+};
+
+// src/tools/graph/QueryGraphTool.ts
+var propertyFilterSchema = {
+  type: "object",
+  properties: {
+    key: { type: "string" },
+    operator: { type: "string", enum: ["eq", "neq", "isNull", "isNotNull", "gt", "lt", "gte", "lte", "contains"] },
+    value: {}
+  },
+  required: ["key", "operator"]
+};
+var QueryGraphTool = class extends BaseToolController {
+  get name() {
+    return "memory_query_graph";
+  }
+  get description() {
+    return `Query the knowledge graph \u2014 vertex lookups, property projection, and multi-hop traversals in a single tool.
+
+## Projection (property extraction and aggregation)
+
+Use \`projection\` to extract property values from entities. When projection is present, only the aggregated values are returned (no entity objects) \u2014 this keeps responses lightweight. Set \`projection.includeEntities: true\` if you also need the full entity objects.
+
+- Distinct values: \`{ start: { entityType: "Equipment" }, projection: { properties: ["equipmentType"], distinct: true }, limit: 200 }\`
+- Count by value: \`{ start: { entityType: "Equipment" }, projection: { properties: ["equipmentType"], mode: "count" }, limit: 200 }\`
+- Multi-property: \`{ start: { entityType: "Equipment" }, projection: { properties: ["equipmentType", "tier"], distinct: true }, limit: 200 }\`
+
+## Vertex queries (no steps, no projection)
+
+Query entities directly by type and properties \u2014 returns entity objects:
+- By type: \`{ start: { entityType: "Fluid" }, limit: 50 }\`
+- With filter: \`{ start: { entityType: "Fluid", filter: [{ key: "fluidType", operator: "eq", value: "hydraulic-oil" }] }, limit: 50 }\`
+
+## Traversals (with steps)
+
+Follow relationships through the graph:
+- 2-hop: \`{ start: { entityId: "Equipment:komatsu-pc7000-11" }, steps: [{ direction: "out", relationshipTypes: ["HAS_COMPONENT"] }, { direction: "out", relationshipTypes: ["REQUIRES_FLUID"] }] }\`
+- Filtered edges: \`{ start: { entityId: "Equipment:komatsu-pc7000-11" }, steps: [{ direction: "both", relationshipTypes: ["COMPATIBLE_WITH"], relationshipFilter: [{ key: "passCount", operator: "gte", value: 3 }] }] }\`
+- Variable depth: \`{ start: { entityId: "..." }, steps: [{ direction: "out", relationshipTypes: ["CONTAINS"], repeat: { maxDepth: 5 } }] }\`
+
+Projection works with traversals too \u2014 add \`projection\` to aggregate properties from the traversal results.`;
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to query" },
+        start: {
+          type: "object",
+          description: "Which entities to query or start traversing from",
+          properties: {
+            entityId: { type: "string", description: "Specific entity by ID (GUID) or slug" },
+            entityType: { type: "string", description: "All entities of a given type (requires limit)" },
+            filter: { type: "array", items: propertyFilterSchema, description: "Filter entities by property values" }
+          }
+        },
+        steps: {
+          type: "array",
+          description: "Relationship hops to follow. Omit for vertex-only queries.",
+          items: {
+            type: "object",
+            properties: {
+              direction: { type: "string", enum: ["out", "in", "both"], description: "Direction to traverse" },
+              relationshipTypes: { type: "array", items: { type: "string" }, description: "Relationship types to follow (omit for all)" },
+              entityTypes: { type: "array", items: { type: "string" }, description: "Filter target entities by type" },
+              relationshipFilter: { type: "array", items: propertyFilterSchema, description: "Filter relationships by property values" },
+              entityFilter: { type: "array", items: propertyFilterSchema, description: "Filter target entities by property values" },
+              repeat: {
+                type: "object",
+                description: "Repeat this step for variable-depth traversal",
+                properties: {
+                  maxDepth: { type: "number", description: "Maximum iterations (required)" },
+                  until: { type: "array", items: propertyFilterSchema, description: "Stop when entity matches these filters" },
+                  emitIntermediates: { type: "boolean", description: "Include intermediate entities (default: true)" }
+                },
+                required: ["maxDepth"]
+              }
+            },
+            required: ["direction"]
+          }
+        },
+        projection: {
+          type: "object",
+          description: "Property projection \u2014 extract and aggregate property values from result entities. When present, only aggregations are returned (no entity objects). Set includeEntities: true to also get entity objects.",
+          properties: {
+            properties: { type: "array", items: { type: "string" }, description: "Property names to extract from entities" },
+            distinct: { type: "boolean", description: "Return only distinct value combinations (default: false)" },
+            mode: { type: "string", enum: ["values", "count"], description: "values (default): raw property values. count: count entities per distinct combination" },
+            includeEntities: { type: "boolean", description: "Also return full entity objects alongside projections (default: false)" }
+          },
+          required: ["properties"]
+        },
+        returnMode: { type: "string", enum: ["terminal", "path", "all"], description: "What to return (default: terminal)" },
+        limit: { type: "number", description: "Maximum results (default: 50, max: 200)" },
+        offset: { type: "number", description: "Pagination offset (default: 0)" },
+        detailLevel: { type: "string", enum: ["brief", "summary", "full"], description: "Detail level for entities (default: summary)" },
+        dedup: { type: "boolean", description: "Deduplicate entities (default: true)" },
+        includeRelationshipSummary: { type: "boolean", description: "Attach outbound/inbound relationship counts by type to each entity (default: true). Set false to reduce response size." }
+      },
+      required: ["repositoryId", "start"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const start = params["start"];
+    if (start.entityId) {
+      start.entityId = await this.resolveEntityId(repo, start.entityId);
+    }
+    const spec = {
+      start,
+      steps: params["steps"],
+      returnMode: params["returnMode"] ?? "terminal",
+      projection: params["projection"],
+      limit: params["limit"],
+      offset: params["offset"],
+      detailLevel: params["detailLevel"],
+      dedup: params["dedup"],
+      includeRelationshipSummary: params["includeRelationshipSummary"] ?? true,
+      includeProvenance: false
+    };
+    return repo.traverse(spec);
+  }
+};
+
+// src/tools/search/SearchByConceptTool.ts
+var SearchByConceptTool = class extends BaseToolController {
+  get name() {
+    return "memory_search_by_concept";
+  }
+  get description() {
+    return "Semantic search for entities by concept similarity (requires an EmbeddingProvider)";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to search in" },
+        query: { type: "string", description: "Natural language search query" },
+        similarityThreshold: { type: "number", description: "Minimum similarity score 0.0-1.0 (default: 0.7)" },
+        entityTypes: { type: "array", items: { type: "string" }, description: "Filter by entity type(s)" },
+        limit: { type: "number", description: "Max results (default 10)" },
+        offset: { type: "number", description: "Pagination offset" },
+        detailLevel: { type: "string", enum: ["brief", "summary", "full"], description: "Detail level for returned entities (default: summary)" }
+      },
+      required: ["repositoryId", "query"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    return repo.searchByConcept(params["query"], {
+      similarityThreshold: params["similarityThreshold"],
+      entityTypes: params["entityTypes"],
+      limit: params["limit"],
+      offset: params["offset"],
+      detailLevel: params["detailLevel"]
+    });
+  }
+};
+
+// src/tools/vocabulary/GetVocabularyTool.ts
+function stripVocabularyProvenance(obj) {
+  const { createdAt, createdBy, modifiedAt, modifiedBy, ...rest } = obj;
+  return rest;
+}
+var GetVocabularyTool = class extends BaseToolController {
+  get name() {
+    return "memory_get_vocabulary";
+  }
+  get description() {
+    return "Get the vocabulary definition for a repository \u2014 shows available entity types, relationship types, and governance mode";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to get vocabulary for" },
+        includeProvenance: { type: "boolean", description: "Include createdAt/createdBy/modifiedAt/modifiedBy on type definitions (default: false)" }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const result = await repo.getVocabulary();
+    const includeProvenance = params["includeProvenance"] === true;
+    if (!includeProvenance) {
+      return {
+        ...result,
+        vocabulary: {
+          ...result.vocabulary,
+          entityTypes: result.vocabulary.entityTypes.map(stripVocabularyProvenance),
+          relationshipTypes: result.vocabulary.relationshipTypes.map(stripVocabularyProvenance)
+        }
+      };
+    }
+    return result;
+  }
+};
+
+// src/tools/vocabulary/ProposeVocabularyExtensionTool.ts
+var ProposeVocabularyExtensionTool = class extends BaseToolController {
+  get name() {
+    return "memory_propose_vocabulary_extension";
+  }
+  get description() {
+    return "Propose a new entity type or relationship type. Only needed when the vocabulary doesn't already include the type you need \u2014 check memory_open_repository response first.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to modify" },
+        proposalType: {
+          type: "string",
+          enum: [
+            "entity_type",
+            "relationship_type",
+            "edit_entity_type",
+            "edit_relationship_type",
+            "delete_entity_type",
+            "delete_relationship_type"
+          ],
+          description: "Type of vocabulary change"
+        },
+        entityType: {
+          type: "object",
+          description: "Entity type definition (when proposalType is entity_type)",
+          properties: {
+            type: { type: "string", description: "Type name" },
+            description: { type: "string", description: "Type description" },
+            properties: { type: "array", items: { type: "object" }, description: "Property schema definitions" }
+          },
+          required: ["type", "description"]
+        },
+        relationshipType: {
+          type: "object",
+          description: "Relationship type definition (when proposalType is relationship_type)",
+          properties: {
+            type: { type: "string", description: "Type name" },
+            description: { type: "string", description: "Type description" },
+            allowedSourceTypes: { type: "array", items: { type: "string" } },
+            allowedTargetTypes: { type: "array", items: { type: "string" } },
+            bidirectional: { type: "boolean" },
+            properties: { type: "array", items: { type: "object" }, description: "Property schema definitions" }
+          },
+          required: ["type", "description", "allowedSourceTypes", "allowedTargetTypes"]
+        },
+        editEntityType: {
+          type: "object",
+          description: "Edit an existing entity type (when proposalType is edit_entity_type)",
+          properties: {
+            type: { type: "string", description: "Name of the entity type to edit" },
+            description: { type: "string", description: "New description (optional)" },
+            addProperties: { type: "array", items: { type: "object" }, description: "Properties to add" },
+            removeProperties: { type: "array", items: { type: "string" }, description: "Property names to remove" },
+            updateProperties: { type: "array", items: { type: "object" }, description: "Properties to update (matched by name)" }
+          },
+          required: ["type"]
+        },
+        editRelationshipType: {
+          type: "object",
+          description: "Edit an existing relationship type (when proposalType is edit_relationship_type)",
+          properties: {
+            type: { type: "string", description: "Name of the relationship type to edit" },
+            description: { type: "string", description: "New description (optional)" },
+            allowedSourceTypes: { type: "array", items: { type: "string" }, description: "New allowed source types" },
+            allowedTargetTypes: { type: "array", items: { type: "string" }, description: "New allowed target types" },
+            bidirectional: { type: "boolean", description: "New bidirectional flag" },
+            addProperties: { type: "array", items: { type: "object" }, description: "Properties to add" },
+            removeProperties: { type: "array", items: { type: "string" }, description: "Property names to remove" },
+            updateProperties: { type: "array", items: { type: "object" }, description: "Properties to update (matched by name)" }
+          },
+          required: ["type"]
+        },
+        deleteEntityType: {
+          type: "object",
+          description: "Delete an entity type and all its instances (when proposalType is delete_entity_type)",
+          properties: {
+            type: { type: "string", description: "Name of the entity type to delete" }
+          },
+          required: ["type"]
+        },
+        deleteRelationshipType: {
+          type: "object",
+          description: "Delete a relationship type and all its instances (when proposalType is delete_relationship_type)",
+          properties: {
+            type: { type: "string", description: "Name of the relationship type to delete" }
+          },
+          required: ["type"]
+        },
+        justification: { type: "string", description: "Why this vocabulary change is needed" }
+      },
+      required: ["repositoryId", "proposalType"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const proposal = {
+      proposalType: params["proposalType"],
+      entityType: params["entityType"],
+      relationshipType: params["relationshipType"],
+      editEntityType: params["editEntityType"],
+      editRelationshipType: params["editRelationshipType"],
+      deleteEntityType: params["deleteEntityType"],
+      deleteRelationshipType: params["deleteRelationshipType"],
+      justification: params["justification"] ?? ""
+    };
+    return repo.proposeVocabularyChange(proposal);
+  }
+};
+
+// src/tools/stats/GetStatsTool.ts
+var GetStatsTool = class extends BaseToolController {
+  get name() {
+    return "memory_get_stats";
+  }
+  get description() {
+    return "Get statistics for a repository \u2014 entity count, relationship count, type breakdowns";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository to get stats for" }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    return repo.getStats();
+  }
+};
+
+// src/tools/stats/GetTimelineTool.ts
+var GetTimelineTool = class extends BaseToolController {
+  get name() {
+    return "memory_get_timeline";
+  }
+  get description() {
+    return "Get the activity timeline for an entity \u2014 creation, updates, and relationship changes. Accepts entity ID (GUID) or slug.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: { type: "string", description: "Repository containing the entity" },
+        entityId: { type: "string", description: "Entity ID (GUID) or slug" },
+        from: { type: "string", description: "Start of time range (ISO 8601)" },
+        to: { type: "string", description: "End of time range (ISO 8601)" },
+        eventTypes: { type: "array", items: { type: "string" }, description: "Filter by event types" },
+        limit: { type: "number", description: "Max events (default 20, max 100)" },
+        offset: { type: "number", description: "Pagination offset" },
+        conversationId: { type: "string", description: "Filter to events from this conversation" },
+        actor: { type: "string", description: "Filter to events by this actor" }
+      },
+      required: ["repositoryId", "entityId"]
+    };
+  }
+  async handleExecute(params) {
+    const repo = await this.context.getRepository(params["repositoryId"]);
+    const resolvedId = await this.resolveEntityId(repo, params["entityId"]);
+    const timeRange = params["from"] && params["to"] ? { from: params["from"], to: params["to"] } : void 0;
+    const rawLimit = params["limit"];
+    const limit = Math.min(rawLimit ?? 20, 100);
+    return repo.getTimeline(resolvedId, {
+      timeRange,
+      eventTypes: params["eventTypes"],
+      limit,
+      offset: params["offset"] ?? 0,
+      provenance: buildProvenanceFilter(params)
+    });
+  }
+};
+
+// src/tools/portability/ExportRepositoryTool.ts
+import { mkdirSync } from "fs";
+import { writeFile } from "fs/promises";
+import { join, resolve } from "path";
+
+// src/tools/portability/zip.ts
+import { deflateRawSync, inflateRawSync } from "zlib";
+var crc32Table = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i;
+  for (let j = 0; j < 8; j++) {
+    c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  }
+  crc32Table[i] = c;
+}
+function computeCrc32(data) {
+  let crc = 4294967295;
+  for (let i = 0; i < data.length; i++) {
+    crc = (crc32Table[(crc ^ data[i]) & 255] ^ crc >>> 8) >>> 0;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function createZip(entries) {
+  const now = /* @__PURE__ */ new Date();
+  const dosTime = (now.getHours() << 11 | now.getMinutes() << 5 | now.getSeconds() >> 1) & 65535;
+  const dosDate = ((now.getFullYear() - 1980 & 127) << 9 | (now.getMonth() + 1 & 15) << 5 | now.getDate() & 31) & 65535;
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const nameBytes = Buffer.from(entry.name, "utf8");
+    const compressed = deflateRawSync(entry.data);
+    const crc = computeCrc32(entry.data);
+    const local = Buffer.allocUnsafe(30 + nameBytes.length);
+    local.writeUInt32LE(67324752, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0, 6);
+    local.writeUInt16LE(8, 8);
+    local.writeUInt16LE(dosTime, 10);
+    local.writeUInt16LE(dosDate, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(compressed.length, 18);
+    local.writeUInt32LE(entry.data.length, 22);
+    local.writeUInt16LE(nameBytes.length, 26);
+    local.writeUInt16LE(0, 28);
+    nameBytes.copy(local, 30);
+    const central = Buffer.allocUnsafe(46 + nameBytes.length);
+    central.writeUInt32LE(33639248, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0, 8);
+    central.writeUInt16LE(8, 10);
+    central.writeUInt16LE(dosTime, 12);
+    central.writeUInt16LE(dosDate, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(compressed.length, 20);
+    central.writeUInt32LE(entry.data.length, 24);
+    central.writeUInt16LE(nameBytes.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(0, 38);
+    central.writeUInt32LE(offset, 42);
+    nameBytes.copy(central, 46);
+    localParts.push(local, compressed);
+    centralParts.push(central);
+    offset += local.length + compressed.length;
+  }
+  const centralDirOffset = offset;
+  const centralDirBuf = Buffer.concat(centralParts);
+  const eocd = Buffer.allocUnsafe(22);
+  eocd.writeUInt32LE(101010256, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(centralDirBuf.length, 12);
+  eocd.writeUInt32LE(centralDirOffset, 16);
+  eocd.writeUInt16LE(0, 20);
+  return Buffer.concat([...localParts, centralDirBuf, eocd]);
+}
+function readZip(zipBuffer) {
+  let eocdOffset = -1;
+  for (let i = zipBuffer.length - 22; i >= 0; i--) {
+    if (zipBuffer.readUInt32LE(i) === 101010256) {
+      eocdOffset = i;
+      break;
+    }
+  }
+  if (eocdOffset === -1) {
+    throw new Error("Invalid ZIP file: end of central directory record not found");
+  }
+  const entryCount = zipBuffer.readUInt16LE(eocdOffset + 10);
+  const centralDirOffset = zipBuffer.readUInt32LE(eocdOffset + 16);
+  const entries = /* @__PURE__ */ new Map();
+  let pos = centralDirOffset;
+  for (let i = 0; i < entryCount; i++) {
+    if (zipBuffer.readUInt32LE(pos) !== 33639248) {
+      throw new Error("Invalid ZIP file: central directory header not found");
+    }
+    const compressionMethod = zipBuffer.readUInt16LE(pos + 10);
+    const compressedSize = zipBuffer.readUInt32LE(pos + 20);
+    const nameLength = zipBuffer.readUInt16LE(pos + 28);
+    const extraLength = zipBuffer.readUInt16LE(pos + 30);
+    const commentLength = zipBuffer.readUInt16LE(pos + 32);
+    const localHeaderOffset = zipBuffer.readUInt32LE(pos + 42);
+    const name = zipBuffer.subarray(pos + 46, pos + 46 + nameLength).toString("utf8");
+    pos += 46 + nameLength + extraLength + commentLength;
+    const localNameLength = zipBuffer.readUInt16LE(localHeaderOffset + 26);
+    const localExtraLength = zipBuffer.readUInt16LE(localHeaderOffset + 28);
+    const dataOffset = localHeaderOffset + 30 + localNameLength + localExtraLength;
+    const compressedData = zipBuffer.subarray(dataOffset, dataOffset + compressedSize);
+    if (compressionMethod === 0) {
+      entries.set(name, Buffer.from(compressedData));
+    } else if (compressionMethod === 8) {
+      entries.set(name, Buffer.from(inflateRawSync(compressedData)));
+    } else {
+      throw new Error(`Unsupported ZIP compression method: ${compressionMethod}`);
+    }
+  }
+  return entries;
+}
+
+// src/tools/portability/ExportRepositoryTool.ts
+var CHUNK_SIZE = 500;
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "repository";
+}
+function formatDatetime(date) {
+  const p = (n) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}-${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`;
+}
+function toBuffer(obj) {
+  return Buffer.from(JSON.stringify(obj, null, 2), "utf8");
+}
+var ExportRepositoryTool = class extends BaseToolController {
+  constructor(context, logger2, exportDir) {
+    super(context, logger2);
+    this.exportDir = exportDir;
+  }
+  exportDir;
+  get name() {
+    return "memory_export_repository";
+  }
+  get description() {
+    return "Export a memory repository to a .dkg (Deep Knowledge Graph) file on the local filesystem. The archive contains manifest.json, vocabulary.json, and chunked entities/relationships files. Returns the path \u2014 no data is sent to the AI.";
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: {
+          type: "string",
+          description: "UUID of the repository to export"
+        },
+        legal: {
+          type: "object",
+          description: "Optional legal/copyright metadata to embed in the archive manifest",
+          properties: {
+            copyright: {
+              type: "string",
+              description: 'Copyright holder (e.g. "\xA9 2026 Caterpillar Inc.")'
+            },
+            license: {
+              type: "string",
+              description: 'SPDX license identifier or custom license name (e.g. "Apache-2.0", "LicenseRef-Proprietary")'
+            },
+            licenseUrl: {
+              type: "string",
+              description: "Full license text or URL pointing to license terms"
+            },
+            terms: {
+              type: "string",
+              description: "Human-readable usage terms or restrictions summary"
+            },
+            publisher: {
+              type: "string",
+              description: "Organization that published this archive"
+            },
+            contact: {
+              type: "string",
+              description: "Contact for licensing questions (e.g. email address)"
+            }
+          },
+          required: ["copyright"]
+        }
+      },
+      required: ["repositoryId"]
+    };
+  }
+  async handleExecute(params) {
+    const repositoryId = params["repositoryId"];
+    const legal = params["legal"];
+    this.logger.info(this.name, `Exporting repository ${repositoryId}`);
+    const startTime = Date.now();
+    const exportOptions = legal ? { legal } : void 0;
+    const entries = [];
+    let entityCount = 0;
+    let relationshipCount = 0;
+    let entityChunkNum = 0;
+    let relationshipChunkNum = 0;
+    let label = "";
+    let vocabVersion = "";
+    let exportedAt = "";
+    for await (const item of this.context.deepMemory.exportRepositoryStream(repositoryId, exportOptions)) {
+      switch (item.type) {
+        case "manifest":
+          entries.push({ name: "manifest.json", data: toBuffer(item.data) });
+          label = item.data.repository.label;
+          vocabVersion = item.data.repository.vocabularyVersion;
+          exportedAt = item.data.exportedAt;
+          break;
+        case "vocabulary":
+          entries.push({ name: "vocabulary.json", data: toBuffer(item.data) });
+          break;
+        case "entities": {
+          const allEntities = item.data;
+          for (let i = 0; i < allEntities.length; i += CHUNK_SIZE) {
+            const chunk = allEntities.slice(i, i + CHUNK_SIZE);
+            entityChunkNum++;
+            entries.push({
+              name: `entities-${String(entityChunkNum).padStart(4, "0")}.json`,
+              data: toBuffer(chunk)
+            });
+          }
+          entityCount += allEntities.length;
+          break;
+        }
+        case "relationships": {
+          const allRels = item.data;
+          for (let i = 0; i < allRels.length; i += CHUNK_SIZE) {
+            const chunk = allRels.slice(i, i + CHUNK_SIZE);
+            relationshipChunkNum++;
+            entries.push({
+              name: `relationships-${String(relationshipChunkNum).padStart(4, "0")}.json`,
+              data: toBuffer(chunk)
+            });
+          }
+          relationshipCount += allRels.length;
+          break;
+        }
+      }
+    }
+    const slug = slugify(label);
+    const datetime = formatDatetime(new Date(exportedAt));
+    const zipName = `${slug}-v${vocabVersion}-${datetime}.dkg`;
+    const exportDir = resolve(this.exportDir);
+    mkdirSync(exportDir, { recursive: true });
+    const filePath = join(exportDir, zipName);
+    const zipBuffer = createZip(entries);
+    await writeFile(filePath, zipBuffer);
+    const elapsedMs = Date.now() - startTime;
+    const elapsedSec = (elapsedMs / 1e3).toFixed(1);
+    this.logger.info(this.name, `Exported to ${filePath} (${entries.length} files) in ${elapsedSec}s`);
+    return {
+      path: filePath,
+      filename: zipName,
+      repository: label,
+      vocabularyVersion: vocabVersion,
+      statistics: {
+        entities: entityCount,
+        relationships: relationshipCount,
+        files: entries.length
+      },
+      timing: {
+        elapsedMs,
+        elapsedFormatted: `${elapsedSec}s`
+      }
+    };
+  }
+};
+
+// src/tools/portability/ImportRepositoryTool.ts
+import { readFile } from "fs/promises";
+var ImportRepositoryTool = class extends BaseToolController {
+  get name() {
+    return "memory_import_repository";
+  }
+  get description() {
+    return 'Import a .dkg (Deep Knowledge Graph) archive. Also accepts legacy .zip archives. Mode "create" creates a new repository and uses fast bulk inserts (no existence checks). Mode "merge" (default) imports into an existing repository \u2014 entities with matching IDs are overwritten; new vocabulary types are added automatically. Supports both multi-file (manifest.json + chunks) and legacy single-file archives.';
+  }
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        repositoryId: {
+          type: "string",
+          description: "UUID of the target repository to import into (merge) or for the new repository (create)"
+        },
+        path: {
+          type: "string",
+          description: "Absolute path to the .dkg or .zip archive to import"
+        },
+        mode: {
+          type: "string",
+          enum: ["create", "merge"],
+          description: 'Import mode: "create" for a new repository (fast, no existence checks), "merge" to import into an existing repository (default: merge)'
+        }
+      },
+      required: ["repositoryId", "path"]
+    };
+  }
+  async handleExecute(params) {
+    const repositoryId = params["repositoryId"];
+    const filePath = params["path"];
+    const mode = params["mode"] ?? "merge";
+    this.logger.info(this.name, `Importing ${filePath} into repository ${repositoryId} (mode: ${mode})`);
+    const startTime = Date.now();
+    const zipBuffer = await readFile(filePath);
+    const files = readZip(zipBuffer);
+    const manifestBuf = files.get("manifest.json");
+    let manifest;
+    let vocabulary;
+    const entities = [];
+    const relationships = [];
+    if (manifestBuf) {
+      manifest = JSON.parse(manifestBuf.toString("utf8"));
+      const vocabBuf = files.get("vocabulary.json");
+      if (!vocabBuf) {
+        throw new Error("Invalid archive: manifest.json present but vocabulary.json missing");
+      }
+      vocabulary = JSON.parse(vocabBuf.toString("utf8"));
+      const sortedNames = [...files.keys()].sort();
+      for (const name of sortedNames) {
+        if (name.startsWith("entities-") && name.endsWith(".json")) {
+          const chunk = JSON.parse(files.get(name).toString("utf8"));
+          entities.push(...chunk);
+        } else if (name.startsWith("relationships-") && name.endsWith(".json")) {
+          const chunk = JSON.parse(files.get(name).toString("utf8"));
+          relationships.push(...chunk);
+        }
+      }
+    } else {
+      const firstEntry = files.values().next().value;
+      if (!firstEntry) {
+        throw new Error("Invalid archive: zip file is empty");
+      }
+      const legacy = JSON.parse(firstEntry.toString("utf8"));
+      manifest = legacy.manifest;
+      vocabulary = legacy.vocabulary;
+      entities.push(...legacy.entities);
+      relationships.push(...legacy.relationships);
+    }
+    const onAdjust = (event) => {
+      this.logger.info(
+        this.name,
+        `Adaptive concurrency ${event.reason}: ${event.previousConcurrency} -> ${event.concurrency} (tasks=${event.tasksCompleted}, throttled=${event.throttledCount})`
+      );
+    };
+    const importOptions = mode === "create" ? {
+      target: {
+        mode: "create",
+        repositoryId,
+        config: {
+          label: manifest.repository.label,
+          type: manifest.repository.type,
+          description: manifest.repository.description,
+          governance: { mode: manifest.repository.governanceMode }
+        }
+      },
+      bulk: {
+        adaptiveConcurrency: { onAdjust }
+      }
+    } : {
+      target: { mode: "merge", repositoryId },
+      vocabularyConflict: "extend",
+      entityConflict: "overwrite",
+      bulk: {
+        adaptiveConcurrency: { onAdjust }
+      }
+    };
+    const result = await this.context.deepMemory.importRepository(
+      { manifest, vocabulary, entities, relationships },
+      importOptions
+    );
+    const elapsedMs = Date.now() - startTime;
+    const elapsedSec = (elapsedMs / 1e3).toFixed(1);
+    this.logger.info(
+      this.name,
+      `Import ${result.success ? "succeeded" : "failed"}: ${result.statistics.entitiesImported} entities, ${result.statistics.relationshipsImported} relationships in ${elapsedSec}s`
+    );
+    return {
+      success: result.success,
+      repositoryId: result.repositoryId,
+      statistics: result.statistics,
+      warnings: result.warnings,
+      timing: {
+        elapsedMs,
+        elapsedFormatted: `${elapsedSec}s`
+      }
+    };
+  }
+};
+
+// src/server/ToolRegistry.ts
+var ToolRegistry = class {
+  constructor(context, logger2) {
+    this.context = context;
+    this.logger = logger2;
+    this.registerTools();
+  }
+  context;
+  logger;
+  tools = /* @__PURE__ */ new Map();
+  registerTools() {
+    this.register(new CreateRepositoryTool(this.context, this.logger));
+    this.register(new OpenRepositoryTool(this.context, this.logger));
+    this.register(new ListRepositoriesTool(this.context, this.logger));
+    this.register(new UpdateRepositoryTool(this.context, this.logger));
+    this.register(new DeleteRepositoryTool(this.context, this.logger));
+    this.register(new EnsureSchemaTool(this.context, this.logger));
+    this.register(new ValidateEntitiesTool(this.context, this.logger));
+    this.register(new ValidateRelationshipsTool(this.context, this.logger));
+    this.register(new CreateEntitiesTool(this.context, this.logger));
+    this.register(new UpdateEntityTool(this.context, this.logger));
+    this.register(new GetEntityTool(this.context, this.logger));
+    this.register(new FindEntitiesTool(this.context, this.logger));
+    this.register(new DeleteEntitiesTool(this.context, this.logger));
+    this.register(new ReembedRepositoryTool(this.context, this.logger));
+    this.register(new CreateRelationshipsTool(this.context, this.logger));
+    this.register(new RemoveRelationshipsTool(this.context, this.logger));
+    this.register(new GetRelationshipsTool(this.context, this.logger));
+    this.register(new ExploreNeighborhoodTool(this.context, this.logger));
+    this.register(new FindPathsTool(this.context, this.logger));
+    this.register(new GetGraphTool(this.context, this.logger));
+    this.register(new QueryGraphTool(this.context, this.logger));
+    this.register(new SearchByConceptTool(this.context, this.logger));
+    this.register(new GetVocabularyTool(this.context, this.logger));
+    this.register(new ProposeVocabularyExtensionTool(this.context, this.logger));
+    this.register(new GetStatsTool(this.context, this.logger));
+    this.register(new GetTimelineTool(this.context, this.logger));
+    this.register(new ExportRepositoryTool(this.context, this.logger, this.context.exportDir));
+    this.register(new ImportRepositoryTool(this.context, this.logger));
+    this.logger.info("ToolRegistry", `Registered ${this.tools.size} tools`);
+  }
+  register(tool) {
+    if (this.tools.has(tool.name)) {
+      this.logger.warn("ToolRegistry", `Tool ${tool.name} already registered, overwriting`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+  listTools() {
+    return Array.from(this.tools.values()).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema
+    }));
+  }
+  async executeTool(name, params) {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new Error(`Tool '${name}' not found`);
+    }
+    this.logger.debug("ToolRegistry", `Executing tool: ${name}`);
+    try {
+      const result = await tool.execute(params);
+      this.logger.debug("ToolRegistry", `Tool ${name} completed`);
+      return result;
+    } catch (error) {
+      this.logger.error("ToolRegistry", `Tool ${name} failed`, error);
+      throw error;
+    }
+  }
+  getToolCount() {
+    return this.tools.size;
+  }
+};
+
+// src/server/McpHandler.ts
+var McpHandler = class {
+  constructor(toolRegistry, logger2) {
+    this.toolRegistry = toolRegistry;
+    this.logger = logger2;
+  }
+  toolRegistry;
+  logger;
+  async handleToolsList() {
+    this.logger.debug("McpHandler", "Received tools/list request");
+    const tools = this.toolRegistry.listTools();
+    this.logger.info("McpHandler", `Returning ${tools.length} tools`);
+    return {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      }))
+    };
+  }
+  async handleToolCall(request) {
+    const { name, arguments: args } = request.params;
+    this.logger.debug("McpHandler", `Received tool call: ${name}`);
+    try {
+      if (!name) {
+        throw new Error("Tool name is required");
+      }
+      const result = await this.toolRegistry.executeTool(name, args ?? {});
+      this.logger.info("McpHandler", `Tool ${name} executed successfully`);
+      if (result && typeof result === "object" && "content" in result && Array.isArray(result["content"])) {
+        return result;
+      }
+      if (typeof result === "string") {
+        return { content: [{ type: "text", text: result }] };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.error("McpHandler", `Tool ${name} failed: ${message}`);
+      return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true
+      };
+    }
+  }
+};
+
+// src/server/McpServer.ts
+var McpServer = class {
+  constructor(config, logger2) {
+    this.logger = logger2;
+    let storage;
+    let graphTraversal;
+    if (config.storageType === "sqlserver") {
+      storage = new SqlServerStorageProvider({
+        connection: {
+          server: config.sqlServerHost,
+          port: config.sqlServerPort ?? 1433,
+          database: config.sqlServerDatabase,
+          user: config.sqlServerUser,
+          password: config.sqlServerPassword,
+          options: {
+            encrypt: false,
+            trustServerCertificate: config.sqlServerTrustCert ?? false
+          }
+        },
+        schema: config.sqlServerSchema ?? "dbo"
+      });
+    } else if (config.storageType === "cosmosdb") {
+      const cosmos = new CosmosDbProvider({
+        endpoint: config.cosmosDbEndpoint,
+        restEndpoint: config.cosmosDbRestEndpoint,
+        key: config.cosmosDbKey,
+        database: config.cosmosDbDatabase,
+        container: config.cosmosDbContainer,
+        rejectUnauthorized: config.cosmosDbRejectUnauthorized ?? true
+      });
+      storage = cosmos;
+      graphTraversal = cosmos;
+    } else {
+      storage = new InMemoryStorageProvider();
+    }
+    const search = config.storageType === "memory" || !config.storageType ? new InMemorySearchProvider() : void 0;
+    const embeddingFactory = config.embeddingsBaseUrl ? ({ model, dimensions }) => new OpenAIEmbeddingProvider({
+      baseUrl: config.embeddingsBaseUrl,
+      model,
+      dimensions,
+      apiKey: config.embeddingsApiKey
+    }) : void 0;
+    this.deepMemory = new DeepMemory({
+      storage,
+      search,
+      embeddingFactory,
+      defaultEmbeddingModel: config.embeddingsModel,
+      defaultEmbeddingDimensions: config.embeddingsDimensions,
+      graphTraversal,
+      provenance: {
+        actorId: config.actorId ?? "mcp-agent",
+        actorType: config.actorType ?? "agent"
+      }
+    });
+    const toolContext = {
+      deepMemory: this.deepMemory,
+      storage,
+      getRepository: this.getRepository.bind(this),
+      evictRepository: this.evictRepository.bind(this),
+      exportDir: config.exportDir ?? "./exports"
+    };
+    const toolRegistry = new ToolRegistry(toolContext, this.logger);
+    this.handler = new McpHandler(toolRegistry, this.logger);
+    this.server = new Server(
+      {
+        name: "@utaba/deep-memory-local-mcp-server",
+        version: "0.1.0"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.setupHandlers();
+  }
+  logger;
+  server;
+  handler;
+  deepMemory;
+  repositories = /* @__PURE__ */ new Map();
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, this.handler.handleToolsList.bind(this.handler));
+    this.server.setRequestHandler(CallToolRequestSchema, this.handler.handleToolCall.bind(this.handler));
+  }
+  async getRepository(repositoryId) {
+    let repo = this.repositories.get(repositoryId);
+    if (!repo) {
+      repo = await this.deepMemory.openRepository(repositoryId);
+      this.repositories.set(repositoryId, repo);
+    }
+    return repo;
+  }
+  evictRepository(repositoryId) {
+    this.repositories.delete(repositoryId);
+  }
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    this.logger.info("McpServer", "Deep Memory MCP server started on stdio");
+    this.deepMemory.ensureSchema().catch((error) => {
+      this.logger.warn("McpServer", `Storage unavailable on startup \u2014 repository tools will fail until storage is reachable: ${error instanceof Error ? error.message : String(error)}`);
+    });
+  }
+  async stop() {
+    this.repositories.clear();
+    await this.deepMemory.dispose();
+    await this.server.close();
+    this.logger.info("McpServer", "Deep Memory MCP server stopped");
+  }
+};
+
+// src/interfaces/ILogger.ts
+var ConsoleLogger = class {
+  debug(context, message) {
+    console.error(`[DEBUG] [${context}] ${message}`);
+  }
+  info(context, message) {
+    console.error(`[INFO] [${context}] ${message}`);
+  }
+  warn(context, message) {
+    console.error(`[WARN] [${context}] ${message}`);
+  }
+  error(context, message, detail) {
+    console.error(`[ERROR] [${context}] ${message}`, detail ?? "");
+  }
+};
+
+// src/index.ts
+function loadEnvFile(path) {
+  if (!existsSync(path)) return;
+  const content = readFileSync(path, "utf8");
+  for (const raw of content.split(/\r?\n/)) {
+    let line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("export ")) line = line.slice("export ".length).trim();
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (!(key in process.env)) {
+      process.env[key] = value;
+    }
+  }
+}
+loadEnvFile(resolve2(process.cwd(), ".env.local"));
+var logger = new ConsoleLogger();
+var storageSetting = process.env["DEEP_MEMORY_STORAGE"];
+var storageType = storageSetting === "sqlserver" ? "sqlserver" : storageSetting === "cosmosdb" ? "cosmosdb" : "memory";
+var server = new McpServer(
+  {
+    actorId: process.env["DEEP_MEMORY_ACTOR_ID"] ?? "mcp-agent",
+    actorType: process.env["DEEP_MEMORY_ACTOR_TYPE"] ?? "agent",
+    embeddingsBaseUrl: process.env["DEEP_MEMORY_EMBEDDINGS_BASE_URL"],
+    embeddingsModel: process.env["DEEP_MEMORY_EMBEDDINGS_MODEL"],
+    embeddingsDimensions: process.env["DEEP_MEMORY_EMBEDDINGS_DIMENSIONS"] ? Number(process.env["DEEP_MEMORY_EMBEDDINGS_DIMENSIONS"]) : void 0,
+    embeddingsApiKey: process.env["DEEP_MEMORY_EMBEDDINGS_API_KEY"],
+    storageType,
+    sqlServerHost: process.env["DEEP_MEMORY_SQL_HOST"],
+    sqlServerPort: process.env["DEEP_MEMORY_SQL_PORT"] ? Number(process.env["DEEP_MEMORY_SQL_PORT"]) : void 0,
+    sqlServerDatabase: process.env["DEEP_MEMORY_SQL_DATABASE"],
+    sqlServerUser: process.env["DEEP_MEMORY_SQL_USER"],
+    sqlServerPassword: process.env["DEEP_MEMORY_SQL_PASSWORD"],
+    sqlServerSchema: process.env["DEEP_MEMORY_SQL_SCHEMA"],
+    sqlServerTrustCert: process.env["DEEP_MEMORY_SQL_TRUST_CERT"] === "true",
+    cosmosDbEndpoint: process.env["DEEP_MEMORY_COSMOSDB_ENDPOINT"],
+    cosmosDbRestEndpoint: process.env["DEEP_MEMORY_COSMOSDB_REST_ENDPOINT"],
+    cosmosDbKey: process.env["DEEP_MEMORY_COSMOSDB_KEY"],
+    cosmosDbDatabase: process.env["DEEP_MEMORY_COSMOSDB_DATABASE"],
+    cosmosDbContainer: process.env["DEEP_MEMORY_COSMOSDB_CONTAINER"],
+    cosmosDbRejectUnauthorized: process.env["DEEP_MEMORY_COSMOSDB_REJECT_UNAUTHORIZED"] !== "false",
+    exportDir: process.env["DEEP_MEMORY_EXPORT_DIR"] ?? "./exports"
+  },
+  logger
+);
+process.on("SIGINT", async () => {
+  await server.stop();
+  process.exit(0);
+});
+process.on("SIGTERM", async () => {
+  await server.stop();
+  process.exit(0);
+});
+server.start().catch((error) => {
+  logger.error("main", "Failed to start MCP server", error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map