Export memories as JSON

Instructions

Implementation Reference

• src/tools/memory-transfer.ts:16-72 (handler)

  The handler function that exports memories, decisions, and pitfalls as a JSON string. Accepts an optional project_path parameter to filter by project; exports all if empty. Queries projects, memories, decisions, and pitfalls tables and returns a JSON-serialized ExportPayload.

  export async function handleMemoryExport(
    db: Database.Database,
    params: { project_path?: string },
  ): Promise<string> {
    let projectId: string | null = null;
    if (params.project_path) {
      const row = db
        .prepare("SELECT id FROM projects WHERE root_path = ?")
        .get(params.project_path) as { id: string } | undefined;
      projectId = row?.id ?? null;
      if (!projectId) {
        return JSON.stringify({
          schema_version: CURRENT_SCHEMA_VERSION,
          exported_at: new Date().toISOString(),
          projects: [],
          memories: [],
          decisions: [],
          pitfalls: [],
        });
      }
    }
  
    const projectsQuery = projectId
      ? db.prepare("SELECT * FROM projects WHERE id = ?").all(projectId)
      : db.prepare("SELECT * FROM projects").all();
  
    const memoriesQuery = projectId
      ? db
          .prepare(
            "SELECT * FROM memories WHERE (project_id = ? OR scope = 'global') AND deleted_at IS NULL",
          )
          .all(projectId)
      : db.prepare("SELECT * FROM memories WHERE deleted_at IS NULL").all();
  
    const decisionsQuery = projectId
      ? db
          .prepare("SELECT * FROM decisions WHERE project_id = ? AND deleted_at IS NULL")
          .all(projectId)
      : db.prepare("SELECT * FROM decisions WHERE deleted_at IS NULL").all();
  
    const pitfallsQuery = projectId
      ? db
          .prepare("SELECT * FROM pitfalls WHERE project_id = ? AND deleted_at IS NULL")
          .all(projectId)
      : db.prepare("SELECT * FROM pitfalls WHERE deleted_at IS NULL").all();
  
    const payload: ExportPayload = {
      schema_version: CURRENT_SCHEMA_VERSION,
      exported_at: new Date().toISOString(),
      projects: projectsQuery,
      memories: memoriesQuery,
      decisions: decisionsQuery,
      pitfalls: pitfallsQuery,
    };
  
    return JSON.stringify(payload, null, 2);
  }

• src/tools/memory-transfer.ts:7-14 (schema)

  ExportPayload interface defining the schema of the exported JSON structure.

  interface ExportPayload {
    schema_version: number;
    exported_at: string;
    projects: any[];
    memories: any[];
    decisions: any[];
    pitfalls: any[];
  }

• src/index.ts:622-645 (registration)

  Registration of the 'memory_export' tool on the MCP server, with its title, description, input schema (with optional project_path), annotations, and handler binding to handleMemoryExport.

  server.registerTool(
    "memory_export",
    {
      title: "Export memories as JSON",
      description: [
        "Export memories, decisions, and pitfalls as a portable JSON document. Read-only.",
        "Use before destructive maintenance (bulk delete, schema migration) so you have a clean restore point, or to transfer state to another memento-mcp instance via `memory_import`. Includes scope, tags, importance, and supersession links so round-trip preserves structure.",
      ].join(" "),
      inputSchema: {
        project_path: z.string().default("").describe("Absolute project path to export. Empty string (default) exports memories across all projects."),
      },
      annotations: {
        title: "Export memories as JSON",
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
      outputSchema: {
        message: z.string().describe("JSON document (as a string) containing `memories`, `decisions`, and `pitfalls` arrays plus a `meta` object with export timestamp and scope."),
      },
    },
    async (params) => textResult(await handleMemoryExport(db, params))
  );