documcp

Instructions

Implementation Reference

• src/memory/export-import.ts:170-345 (handler)

  Core handler implementation for memory_export_advanced tool. The exportMemories method in MemoryExportImportSystem handles advanced export with formats (json,jsonl,csv,xml,yaml,sqlite,archive), compression (gzip,zip), anonymization, encryption, filters, and includes learning/knowledge graph data.

  async exportMemories(
    outputPath: string,
    options: Partial<ExportOptions> = {},
  ): Promise<ExportResult> {
    const defaultOptions: ExportOptions = {
      format: "json",
      compression: "none",
      includeMetadata: true,
      includeLearning: true,
      includeKnowledgeGraph: true,
      anonymize: {
        enabled: false,
        fields: ["userId", "email", "personalInfo"],
        method: "hash",
      },
      encryption: {
        enabled: false,
        algorithm: "aes-256-gcm",
      },
    };
  
    const activeOptions = { ...defaultOptions, ...options };
    const startTime = Date.now();
  
    this.emit("export_started", { outputPath, options: activeOptions });
  
    try {
      // Get filtered entries
      const entries = await this.getFilteredEntries(activeOptions.filters);
  
      // Prepare export data
      const exportData = await this.prepareExportData(entries, activeOptions);
  
      // Apply anonymization if enabled
      if (activeOptions.anonymize?.enabled) {
        this.applyAnonymization(exportData, activeOptions.anonymize);
      }
  
      // Prepare output path - if compression is requested, use temp file first
      let actualOutputPath = outputPath;
      if (activeOptions.compression && activeOptions.compression !== "none") {
        // For compressed exports, export to temp file first
        if (outputPath.endsWith(".gz")) {
          actualOutputPath = outputPath.slice(0, -3); // Remove .gz suffix
        } else if (outputPath.endsWith(".zip")) {
          actualOutputPath = outputPath.slice(0, -4); // Remove .zip suffix
        }
      }
  
      // Export to specified format
      let filePath: string;
      let size = 0;
  
      switch (activeOptions.format) {
        case "json":
          filePath = await this.exportToJSON(
            actualOutputPath,
            exportData,
            activeOptions,
          );
          break;
        case "jsonl":
          filePath = await this.exportToJSONL(
            actualOutputPath,
            exportData,
            activeOptions,
          );
          break;
        case "csv":
          filePath = await this.exportToCSV(
            actualOutputPath,
            exportData,
            activeOptions,
          );
          break;
        case "xml":
          filePath = await this.exportToXML(
            actualOutputPath,
            exportData,
            activeOptions,
          );
          break;
        case "yaml":
          filePath = await this.exportToYAML(
            actualOutputPath,
            exportData,
            activeOptions,
          );
          break;
        case "sqlite":
          filePath = await this.exportToSQLite(
            actualOutputPath,
            exportData,
            activeOptions,
          );
          break;
        case "archive":
          filePath = await this.exportToArchive(
            actualOutputPath,
            exportData,
            activeOptions,
          );
          break;
        default:
          throw new Error(`Unsupported export format: ${activeOptions.format}`);
      }
  
      // Apply compression if specified
      if (activeOptions.compression && activeOptions.compression !== "none") {
        filePath = await this.applyCompression(
          filePath,
          activeOptions.compression,
          outputPath,
        );
      }
  
      // Apply encryption if enabled
      if (activeOptions.encryption?.enabled) {
        filePath = await this.applyEncryption(
          filePath,
          activeOptions.encryption,
        );
      }
  
      // Get file size
      const stats = await fs.stat(filePath);
      size = stats.size;
  
      const result: ExportResult = {
        success: true,
        filePath,
        format: activeOptions.format,
        size,
        entries: entries.length,
        metadata: {
          exportedAt: new Date(),
          version: this.version,
          source: "DocuMCP Memory System",
          includes: this.getIncludedComponents(activeOptions),
          compression:
            activeOptions.compression !== "none"
              ? activeOptions.compression
              : undefined,
          encryption: activeOptions.encryption?.enabled,
        },
        warnings: [],
        errors: [],
      };
  
      this.emit("export_completed", {
        result,
        duration: Date.now() - startTime,
      });
  
      return result;
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      this.emit("export_error", { error: errorMessage });
  
      return {
        success: false,
        format: activeOptions.format,
        size: 0,
        entries: 0,
        metadata: {
          exportedAt: new Date(),
          version: this.version,
          source: "DocuMCP Memory System",
          includes: [],
        },
        warnings: [],
        errors: [errorMessage],
      };
    }
  }

• src/memory/export-import.ts:15-38 (schema)

  Type definition for ExportOptions used in the input schema of memory_export_advanced.

  export interface ExportOptions {
    format: "json" | "jsonl" | "csv" | "xml" | "yaml" | "sqlite" | "archive";
    compression?: "gzip" | "zip" | "none";
    includeMetadata: boolean;
    includeLearning: boolean;
    includeKnowledgeGraph: boolean;
    filters?: {
      types?: string[];
      dateRange?: { start: Date; end: Date };
      projects?: string[];
      tags?: string[];
      outcomes?: string[];
    };
    anonymize?: {
      enabled: boolean;
      fields: string[];
      method: "hash" | "remove" | "pseudonymize";
    };
    encryption?: {
      enabled: boolean;
      algorithm: "aes-256-gcm" | "aes-192-gcm" | "aes-128-gcm";
      password?: string;
    };
  }

• src/memory/index.ts:603-678 (registration)

  Tool registration and input schema definition for memory_export_advanced in the memoryTools export array.

  {
    name: "memory_export_advanced",
    description: "Advanced memory export with multiple formats and options",
    inputSchema: {
      type: "object",
      properties: {
        outputPath: { type: "string", description: "Output file path" },
        options: {
          type: "object",
          properties: {
            format: {
              type: "string",
              enum: [
                "json",
                "jsonl",
                "csv",
                "xml",
                "yaml",
                "sqlite",
                "archive",
              ],
              default: "json",
            },
            compression: {
              type: "string",
              enum: ["gzip", "zip", "none"],
              default: "none",
            },
            includeMetadata: { type: "boolean", default: true },
            includeLearning: { type: "boolean", default: true },
            includeKnowledgeGraph: { type: "boolean", default: true },
            filters: {
              type: "object",
              properties: {
                types: { type: "array", items: { type: "string" } },
                dateRange: {
                  type: "object",
                  properties: {
                    start: { type: "string", format: "date-time" },
                    end: { type: "string", format: "date-time" },
                  },
                },
                projects: { type: "array", items: { type: "string" } },
                tags: { type: "array", items: { type: "string" } },
                outcomes: { type: "array", items: { type: "string" } },
              },
            },
            anonymize: {
              type: "object",
              properties: {
                enabled: { type: "boolean", default: false },
                fields: { type: "array", items: { type: "string" } },
                method: {
                  type: "string",
                  enum: ["hash", "remove", "pseudonymize"],
                  default: "hash",
                },
              },
            },
            encryption: {
              type: "object",
              properties: {
                enabled: { type: "boolean", default: false },
                algorithm: {
                  type: "string",
                  enum: ["aes-256-gcm", "aes-192-gcm", "aes-128-gcm"],
                  default: "aes-256-gcm",
                },
                password: { type: "string" },
              },
            },
          },
        },
      },
      required: ["outputPath"],
    },

• src/memory/export-import.ts:642-695 (helper)

  Helper method for filtering memory entries based on export options (types, date range, projects, tags, outcomes).

    filters?: ExportOptions["filters"],
  ): Promise<MemoryEntry[]> {
    let entries = await this.storage.getAll();
  
    if (!filters) return entries;
  
    // Apply type filter
    if (filters.types && filters.types.length > 0) {
      entries = entries.filter((entry) => filters.types!.includes(entry.type));
    }
  
    // Apply date range filter
    if (filters.dateRange) {
      entries = entries.filter((entry) => {
        const entryDate = new Date(entry.timestamp);
        return (
          entryDate >= filters.dateRange!.start &&
          entryDate <= filters.dateRange!.end
        );
      });
    }
  
    // Apply project filter
    if (filters.projects && filters.projects.length > 0) {
      entries = entries.filter((entry) =>
        filters.projects!.some(
          (project) =>
            entry.data.projectPath?.includes(project) ||
            entry.data.projectId === project,
        ),
      );
    }
  
    // Apply tags filter
    if (filters.tags && filters.tags.length > 0) {
      entries = entries.filter(
        (entry) => entry.tags?.some((tag) => filters.tags!.includes(tag)),
      );
    }
  
    // Apply outcomes filter
    if (filters.outcomes && filters.outcomes.length > 0) {
      entries = entries.filter(
        (entry) =>
          filters.outcomes!.includes(entry.data.outcome) ||
          (entry.data.success === true &&
            filters.outcomes!.includes("success")) ||
          (entry.data.success === false &&
            filters.outcomes!.includes("failure")),
      );
    }
  
    return entries;
  }

• src/memory/export-import.ts:697-737 (helper)

  Prepares comprehensive export data including memories, optional learning system data and knowledge graph.

  private async prepareExportData(
    entries: MemoryEntry[],
    options: ExportOptions,
  ): Promise<any> {
    const exportData: any = {
      metadata: {
        version: this.version,
        exportedAt: new Date().toISOString(),
        source: "DocuMCP Memory System",
        entries: entries.length,
        options: {
          includeMetadata: options.includeMetadata,
          includeLearning: options.includeLearning,
          includeKnowledgeGraph: options.includeKnowledgeGraph,
        },
      },
      memories: entries,
    };
  
    // Include learning data if requested
    if (options.includeLearning) {
      const patterns = await this.learningSystem.getPatterns();
      exportData.learning = {
        patterns,
        statistics: await this.learningSystem.getStatistics(),
      };
    }
  
    // Include knowledge graph if requested
    if (options.includeKnowledgeGraph) {
      const nodes = await this.knowledgeGraph.getAllNodes();
      const edges = await this.knowledgeGraph.getAllEdges();
      exportData.knowledgeGraph = {
        nodes,
        edges,
        statistics: await this.knowledgeGraph.getStatistics(),
      };
    }
  
    return exportData;
  }