feat: support memory import and export (#1521)

* feat: support memory import and export

* fix(memory): address review feedback

* style: format memory settings page

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

frontend/src/app/api/memory/[...path]/route.ts

@@ -0,0 +1,55 @@
+import type { NextRequest } from "next/server";
+
+const BACKEND_BASE_URL =
+  process.env.NEXT_PUBLIC_BACKEND_BASE_URL ?? "http://127.0.0.1:8001";
+
+function buildBackendUrl(pathname: string) {
+  return new URL(pathname, BACKEND_BASE_URL);
+}
+
+async function proxyRequest(request: NextRequest, pathname: string) {
+  const headers = new Headers(request.headers);
+  headers.delete("host");
+  headers.delete("connection");
+  headers.delete("content-length");
+
+  const hasBody = !["GET", "HEAD"].includes(request.method);
+  const response = await fetch(buildBackendUrl(pathname), {
+    method: request.method,
+    headers,
+    body: hasBody ? await request.arrayBuffer() : undefined,
+  });
+
+  return new Response(await response.arrayBuffer(), {
+    status: response.status,
+    headers: response.headers,
+  });
+}
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> },
+) {
+  return proxyRequest(request, `/api/memory/${(await params).path.join("/")}`);
+}
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> },
+) {
+  return proxyRequest(request, `/api/memory/${(await params).path.join("/")}`);
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> },
+) {
+  return proxyRequest(request, `/api/memory/${(await params).path.join("/")}`);
+}
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> },
+) {
+  return proxyRequest(request, `/api/memory/${(await params).path.join("/")}`);
+}

frontend/src/app/api/memory/route.ts

@@ -0,0 +1,35 @@
+import type { NextRequest } from "next/server";
+
+const BACKEND_BASE_URL =
+  process.env.NEXT_PUBLIC_BACKEND_BASE_URL ?? "http://127.0.0.1:8010";
+
+function buildBackendUrl(pathname: string) {
+  return new URL(pathname, BACKEND_BASE_URL);
+}
+
+async function proxyRequest(request: NextRequest, pathname: string) {
+  const headers = new Headers(request.headers);
+  headers.delete("host");
+  headers.delete("connection");
+  headers.delete("content-length");
+
+  const hasBody = !["GET", "HEAD"].includes(request.method);
+  const response = await fetch(buildBackendUrl(pathname), {
+    method: request.method,
+    headers,
+    body: hasBody ? await request.arrayBuffer() : undefined,
+  });
+
+  return new Response(await response.arrayBuffer(), {
+    status: response.status,
+    headers: response.headers,
+  });
+}
+
+export async function GET(request: NextRequest) {
+  return proxyRequest(request, "/api/memory");
+}
+
+export async function DELETE(request: NextRequest) {
+  return proxyRequest(request, "/api/memory");
+}

frontend/src/components/workspace/settings/memory-settings-page.tsx

@@ -1,8 +1,14 @@
 "use client";
 
-import { PenLineIcon, PlusIcon, Trash2Icon } from "lucide-react";
+import {
+  DownloadIcon,
+  PenLineIcon,
+  PlusIcon,
+  Trash2Icon,
+  UploadIcon,
+} from "lucide-react";
 import Link from "next/link";
-import { useDeferredValue, useId, useState } from "react";
+import { useDeferredValue, useId, useRef, useState } from "react";
 import { toast } from "sonner";
 import { Streamdown } from "streamdown";
 
@@ -19,10 +25,12 @@ import { Input } from "@/components/ui/input";
 import { Textarea } from "@/components/ui/textarea";
 import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { useI18n } from "@/core/i18n/hooks";
+import { exportMemory } from "@/core/memory/api";
 import {
   useClearMemory,
   useCreateMemoryFact,
   useDeleteMemoryFact,
+  useImportMemory,
   useMemory,
   useUpdateMemoryFact,
 } from "@/core/memory/hooks";
@@ -51,6 +59,65 @@ type MemorySectionGroup = {
   sections: MemorySection[];
 };
 
+type PendingImport = {
+  fileName: string;
+  memory: UserMemory;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isMemorySection(value: unknown): value is {
+  summary: string;
+  updatedAt: string;
+} {
+  return (
+    isRecord(value) &&
+    typeof value.summary === "string" &&
+    typeof value.updatedAt === "string"
+  );
+}
+
+function isMemoryFact(value: unknown): value is UserMemory["facts"][number] {
+  return (
+    isRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.content === "string" &&
+    typeof value.category === "string" &&
+    typeof value.confidence === "number" &&
+    Number.isFinite(value.confidence) &&
+    typeof value.createdAt === "string" &&
+    typeof value.source === "string"
+  );
+}
+
+function isImportedMemory(value: unknown): value is UserMemory {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  if (
+    typeof value.version !== "string" ||
+    typeof value.lastUpdated !== "string" ||
+    !isRecord(value.user) ||
+    !isRecord(value.history) ||
+    !Array.isArray(value.facts)
+  ) {
+    return false;
+  }
+
+  return (
+    isMemorySection(value.user.workContext) &&
+    isMemorySection(value.user.personalContext) &&
+    isMemorySection(value.user.topOfMind) &&
+    isMemorySection(value.history.recentMonths) &&
+    isMemorySection(value.history.earlierContext) &&
+    isMemorySection(value.history.longTermBackground) &&
+    value.facts.every(isMemoryFact)
+  );
+}
+
 type FactFormState = {
   content: string;
   category: string;
@@ -212,6 +279,8 @@ export function MemorySettingsPage() {
   const clearMemory = useClearMemory();
   const createMemoryFact = useCreateMemoryFact();
   const deleteMemoryFact = useDeleteMemoryFact();
+  const importMemoryMutation = useImportMemory();
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
   const updateMemoryFact = useUpdateMemoryFact();
   const [clearDialogOpen, setClearDialogOpen] = useState(false);
   const [factToDelete, setFactToDelete] = useState<MemoryFact | null>(null);
@@ -222,6 +291,10 @@ export function MemorySettingsPage() {
   );
   const [query, setQuery] = useState("");
   const [filter, setFilter] = useState<MemoryViewFilter>("all");
+  const [pendingImport, setPendingImport] = useState<PendingImport | null>(
+    null,
+  );
+  const [isExporting, setIsExporting] = useState(false);
   const deferredQuery = useDeferredValue(query);
   const normalizedQuery = deferredQuery.trim().toLowerCase();
   const factContentInputId = useId();
@@ -258,7 +331,6 @@ export function MemorySettingsPage() {
   const factSave = t.settings.memory.factSave;
   const factValidationContent = t.settings.memory.factValidationContent;
   const factValidationConfidence = t.settings.memory.factValidationConfidence;
-  const manualFactSource = t.settings.memory.manualFactSource;
   const noFacts = t.settings.memory.noFacts ?? "No saved facts yet.";
   const summaryReadOnly = t.settings.memory.summaryReadOnly;
   const memoryFullyEmpty =
@@ -271,6 +343,11 @@ export function MemorySettingsPage() {
   const filterFacts = t.settings.memory.filterFacts ?? "Facts";
   const filterSummaries = t.settings.memory.filterSummaries ?? "Summaries";
   const noMatches = t.settings.memory.noMatches ?? "No matching memory found";
+  const exportButton = t.settings.memory.exportButton ?? t.common.export;
+  const exportSuccess =
+    t.settings.memory.exportSuccess ?? t.common.exportSuccess;
+  const importButton = t.settings.memory.importButton ?? t.common.import;
+  const importSuccess = t.settings.memory.importSuccess ?? "Memory imported";
 
   const sectionGroups = memory ? buildMemorySectionGroups(memory, t) : [];
   const filteredSectionGroups = sectionGroups
@@ -308,6 +385,68 @@ export function MemorySettingsPage() {
     (showSummaries && filteredSectionGroups.length > 0) ||
     (showFacts && filteredFacts.length > 0);
 
+  async function handleExportMemory() {
+    try {
+      setIsExporting(true);
+      const exportedMemory = await exportMemory();
+      const fileName = `deerflow-memory-${(exportedMemory.lastUpdated || new Date().toISOString()).replace(/[:.]/g, "-")}.json`;
+      const blob = new Blob([JSON.stringify(exportedMemory, null, 2)], {
+        type: "application/json",
+      });
+      const url = URL.createObjectURL(blob);
+      const link = document.createElement("a");
+      link.href = url;
+      link.download = fileName;
+      document.body.appendChild(link);
+      link.click();
+      link.remove();
+      URL.revokeObjectURL(url);
+      toast.success(exportSuccess);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    } finally {
+      setIsExporting(false);
+    }
+  }
+
+  async function handleImportFileSelection(event: {
+    target: HTMLInputElement;
+  }) {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+    if (!file) {
+      return;
+    }
+
+    try {
+      const parsed: unknown = JSON.parse(await file.text());
+      if (!isImportedMemory(parsed)) {
+        toast.error(t.settings.memory.importInvalidFile);
+        return;
+      }
+      setPendingImport({
+        fileName: file.name,
+        memory: parsed,
+      });
+    } catch {
+      toast.error(t.settings.memory.importInvalidFile);
+    }
+  }
+
+  async function handleConfirmImport() {
+    if (!pendingImport) {
+      return;
+    }
+
+    try {
+      await importMemoryMutation.mutateAsync(pendingImport.memory);
+      toast.success(importSuccess);
+      setPendingImport(null);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
   async function handleClearMemory() {
     try {
       await clearMemory.mutateAsync();
@@ -416,7 +555,7 @@ export function MemorySettingsPage() {
               </div>
             ) : null}
 
-            <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+            <div className="flex flex-col gap-3 xl:flex-row xl:items-center xl:justify-between">
               <div className="flex flex-1 flex-col gap-3 sm:flex-row sm:items-center">
                 <Input
                   value={query}
@@ -440,7 +579,30 @@ export function MemorySettingsPage() {
                 </ToggleGroup>
               </div>
 
-              <div className="flex items-center gap-2">
+              <div className="flex flex-wrap gap-2">
+                <input
+                  ref={fileInputRef}
+                  type="file"
+                  accept=".json,application/json"
+                  className="hidden"
+                  onChange={(event) => void handleImportFileSelection(event)}
+                />
+                <Button
+                  variant="outline"
+                  onClick={() => fileInputRef.current?.click()}
+                  disabled={importMemoryMutation.isPending}
+                >
+                  <UploadIcon className="mr-2 h-4 w-4" />
+                  {importButton}
+                </Button>
+                <Button
+                  variant="outline"
+                  onClick={() => void handleExportMemory()}
+                  disabled={isExporting}
+                >
+                  <DownloadIcon className="mr-2 h-4 w-4" />
+                  {isExporting ? t.common.loading : exportButton}
+                </Button>
                 <Button variant="outline" onClick={openCreateFactDialog}>
                   <PlusIcon className="mr-2 h-4 w-4" />
                   {addFactLabel}
@@ -519,22 +681,25 @@ export function MemorySettingsPage() {
                                 </span>{" "}
                                 {formatTimeAgo(fact.createdAt)}
                               </span>
+                              <span>
+                                <span className="text-muted-foreground">
+                                  {t.settings.memory.markdown.table.source}:
+                                </span>{" "}
+                                {fact.source === "manual" ? (
+                                  t.settings.memory.manualFactSource
+                                ) : (
+                                  <Link
+                                    href={pathOfThread(fact.source)}
+                                    className="text-primary underline-offset-4 hover:underline"
+                                  >
+                                    {t.settings.memory.markdown.table.view}
+                                  </Link>
+                                )}
+                              </span>
                             </div>
                             <p className="text-sm break-words">
                               {fact.content}
                             </p>
-                            {fact.source === "manual" ? (
-                              <span className="text-muted-foreground text-sm">
-                                {manualFactSource}
-                              </span>
-                            ) : (
-                              <Link
-                                href={pathOfThread(fact.source)}
-                                className="text-primary text-sm underline-offset-4 hover:underline"
-                              >
-                                {t.settings.memory.markdown.table.view}
-                              </Link>
-                            )}
                           </div>
 
                           <div className="flex shrink-0 items-center gap-1 self-start sm:ml-3">
@@ -753,6 +918,65 @@ export function MemorySettingsPage() {
           </DialogFooter>
         </DialogContent>
       </Dialog>
+
+      <Dialog
+        open={pendingImport !== null}
+        onOpenChange={(open) => {
+          if (!open) {
+            setPendingImport(null);
+          }
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>{t.settings.memory.importConfirmTitle}</DialogTitle>
+            <DialogDescription>
+              {t.settings.memory.importConfirmDescription}
+            </DialogDescription>
+          </DialogHeader>
+          {pendingImport ? (
+            <div className="bg-muted rounded-md border p-3 text-sm">
+              <div>
+                <span className="text-muted-foreground">
+                  {t.settings.memory.importFileLabel}:
+                </span>{" "}
+                {pendingImport.fileName}
+              </div>
+              <div>
+                <span className="text-muted-foreground">
+                  {t.settings.memory.markdown.facts}:
+                </span>{" "}
+                {pendingImport.memory.facts.length}
+              </div>
+              <div>
+                <span className="text-muted-foreground">
+                  {t.common.lastUpdated}:
+                </span>{" "}
+                {pendingImport.memory.lastUpdated
+                  ? formatTimeAgo(pendingImport.memory.lastUpdated)
+                  : "-"}
+              </div>
+            </div>
+          ) : null}
+          <DialogFooter>
+            <Button
+              variant="outline"
+              onClick={() => setPendingImport(null)}
+              disabled={importMemoryMutation.isPending}
+            >
+              {t.common.cancel}
+            </Button>
+            <Button
+              onClick={() => void handleConfirmImport()}
+              disabled={importMemoryMutation.isPending}
+            >
+              {importMemoryMutation.isPending
+                ? t.common.loading
+                : t.common.import}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </>
   );
 }

frontend/src/core/i18n/locales/en-US.ts

@@ -44,6 +44,7 @@ export const enUS: Translations = {
     save: "Save",
     install: "Install",
     create: "Create",
+    import: "Import",
     export: "Export",
     exportAsMarkdown: "Export as Markdown",
     exportAsJSON: "Export as JSON",
@@ -313,6 +314,17 @@ export const enUS: Translations = {
         "DeerFlow automatically learns from your conversations in the background. These memories help DeerFlow understand you better and deliver a more personalized experience.",
       empty: "No memory data to display.",
       rawJson: "Raw JSON",
+      exportButton: "Export memory",
+      exportSuccess: "Memory exported",
+      importButton: "Import memory",
+      importConfirmTitle: "Import memory?",
+      importConfirmDescription:
+        "This will overwrite your current memory with the selected JSON backup.",
+      importFileLabel: "Selected file",
+      importInvalidFile:
+        "Failed to read the selected memory file. Please choose a valid JSON export.",
+      importSuccess: "Memory imported",
+      manualFactSource: "Manual",
       addFact: "Add fact",
       addFactTitle: "Add memory fact",
       editFactTitle: "Edit memory fact",
@@ -336,7 +348,6 @@ export const enUS: Translations = {
       factSave: "Save fact",
       factValidationContent: "Fact content cannot be empty.",
       factValidationConfidence: "Confidence must be a number between 0 and 1.",
-      manualFactSource: "Manual",
       noFacts: "No saved facts yet.",
       summaryReadOnly:
         "Summary sections are read-only for now. You can currently add, edit, or delete individual facts, or clear all memory.",

frontend/src/core/i18n/locales/types.ts

@@ -33,6 +33,7 @@ export interface Translations {
     save: string;
     install: string;
     create: string;
+    import: string;
     export: string;
     exportAsMarkdown: string;
     exportAsJSON: string;
@@ -248,6 +249,15 @@ export interface Translations {
       description: string;
       empty: string;
       rawJson: string;
+      exportButton: string;
+      exportSuccess: string;
+      importButton: string;
+      importConfirmTitle: string;
+      importConfirmDescription: string;
+      importFileLabel: string;
+      importInvalidFile: string;
+      importSuccess: string;
+      manualFactSource: string;
       addFact: string;
       addFactTitle: string;
       editFactTitle: string;
@@ -269,7 +279,6 @@ export interface Translations {
       factSave: string;
       factValidationContent: string;
       factValidationConfidence: string;
-      manualFactSource: string;
       noFacts: string;
       summaryReadOnly: string;
       memoryFullyEmpty: string;

frontend/src/core/i18n/locales/zh-CN.ts

@@ -1,4 +1,4 @@
-import {
+import {
   CompassIcon,
   GraduationCapIcon,
   ImageIcon,
@@ -44,6 +44,7 @@ export const zhCN: Translations = {
     save: "保存",
     install: "安装",
     create: "创建",
+    import: "导入",
     export: "导出",
     exportAsMarkdown: "导出为 Markdown",
     exportAsJSON: "导出为 JSON",
@@ -299,6 +300,15 @@ export const zhCN: Translations = {
         "DeerFlow 会在后台不断从你的对话中自动学习。这些记忆能帮助 DeerFlow 更好地理解你，并提供更个性化的体验。",
       empty: "暂无可展示的记忆数据。",
       rawJson: "原始 JSON",
+      exportButton: "导出记忆",
+      exportSuccess: "记忆已导出",
+      importButton: "导入记忆",
+      importConfirmTitle: "导入记忆？",
+      importConfirmDescription: "这会用选中的 JSON 备份覆盖当前记忆。",
+      importFileLabel: "已选择文件",
+      importInvalidFile: "读取记忆文件失败，请选择有效的 JSON 导出文件。",
+      importSuccess: "记忆已导入",
+      manualFactSource: "手动添加",
       addFact: "添加事实",
       addFactTitle: "添加记忆事实",
       editFactTitle: "编辑记忆事实",
@@ -322,10 +332,9 @@ export const zhCN: Translations = {
       factSave: "保存事实",
       factValidationContent: "事实内容不能为空。",
       factValidationConfidence: "置信度必须是 0 到 1 之间的数字。",
-      manualFactSource: "手动添加",
       noFacts: "还没有保存的事实。",
       summaryReadOnly:
-        "摘要分区当前仍为只读。你可以在下方添加、编辑或删除事实，或清空全部记忆。",
+        "摘要分区当前仍为只读。现在你可以清空全部记忆或删除单条事实。",
       memoryFullyEmpty: "还没有保存任何记忆。",
       factPreviewLabel: "即将删除的事实",
       searchPlaceholder: "搜索记忆",

frontend/src/core/memory/api.ts

@@ -10,12 +10,69 @@ async function readMemoryResponse(
   response: Response,
   fallbackMessage: string,
 ): Promise<UserMemory> {
+  function formatErrorDetail(detail: unknown): string | null {
+    if (typeof detail === "string") {
+      return detail;
+    }
+
+    if (Array.isArray(detail)) {
+      const parts = detail
+        .map((item) => {
+          if (typeof item === "string") {
+            return item;
+          }
+
+          if (item && typeof item === "object") {
+            const record = item as Record<string, unknown>;
+            if (typeof record.msg === "string") {
+              return record.msg;
+            }
+
+            try {
+              return JSON.stringify(record);
+            } catch {
+              return null;
+            }
+          }
+
+          return String(item);
+        })
+        .filter(Boolean);
+
+      return parts.length > 0 ? parts.join("; ") : null;
+    }
+
+    if (detail && typeof detail === "object") {
+      try {
+        return JSON.stringify(detail);
+      } catch {
+        return null;
+      }
+    }
+
+    if (
+      typeof detail === "string" ||
+      typeof detail === "number" ||
+      typeof detail === "boolean" ||
+      typeof detail === "bigint"
+    ) {
+      return String(detail);
+    }
+
+    if (typeof detail === "symbol") {
+      return detail.description ?? null;
+    }
+
+    return null;
+  }
+
   if (!response.ok) {
     const errorData = (await response.json().catch(() => ({}))) as {
-      detail?: string;
+      detail?: unknown;
     };
+    const detailMessage = formatErrorDetail(errorData.detail);
     throw new Error(
-      errorData.detail ?? `${fallbackMessage}: ${response.statusText}`,
+      detailMessage ?? `${fallbackMessage}: ${response.statusText}`,
     );
   }
 
@@ -44,6 +101,22 @@ export async function deleteMemoryFact(factId: string): Promise<UserMemory> {
   return readMemoryResponse(response, "Failed to delete memory fact");
 }
 
+export async function exportMemory(): Promise<UserMemory> {
+  const response = await fetch(`${getBackendBaseURL()}/api/memory/export`);
+  return readMemoryResponse(response, "Failed to export memory");
+}
+
+export async function importMemory(memory: UserMemory): Promise<UserMemory> {
+  const response = await fetch(`${getBackendBaseURL()}/api/memory/import`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(memory),
+  });
+  return readMemoryResponse(response, "Failed to import memory");
+}
+
 export async function createMemoryFact(
   input: MemoryFactInput,
 ): Promise<UserMemory> {

frontend/src/core/memory/hooks.ts

@@ -4,6 +4,7 @@ import {
   clearMemory,
   createMemoryFact,
   deleteMemoryFact,
+  importMemory,
   loadMemory,
   updateMemoryFact,
 } from "./api";
@@ -43,6 +44,17 @@ export function useDeleteMemoryFact() {
   });
 }
 
+export function useImportMemory() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (memory: UserMemory) => importMemory(memory),
+    onSuccess: (memory) => {
+      queryClient.setQueryData<UserMemory>(["memory"], memory);
+    },
+  });
+}
+
 export function useCreateMemoryFact() {
   const queryClient = useQueryClient();