feat: add memory management actions and local filters in memory settings (#1467)

* Add MVP memory management actions

* Fix memory settings locale coverage

* Polish memory management interactions

* Add memory search and type filters

* Refine memory settings review feedback

* docs: simplify memory settings review setup

* fix: restore memory updater compatibility helpers

* fix: address memory settings review feedback

* docs: soften memory sample review wording

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
Co-authored-by: JeffJiang <for-eleven@hotmail.com>

backend/app/gateway/routers/memory.py

@@ -1,9 +1,14 @@
 """Memory API router for retrieving and managing global memory data."""
 
-from fastapi import APIRouter
+from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
 
-from deerflow.agents.memory.updater import get_memory_data, reload_memory_data
+from deerflow.agents.memory.updater import (
+    clear_memory_data,
+    delete_memory_fact,
+    get_memory_data,
+    reload_memory_data,
+)
 from deerflow.config.memory_config import get_memory_config
 
 router = APIRouter(prefix="/api", tags=["memory"])
@@ -135,6 +140,40 @@ async def reload_memory() -> MemoryResponse:
     return MemoryResponse(**memory_data)
 
 
+@router.delete(
+    "/memory",
+    response_model=MemoryResponse,
+    summary="Clear All Memory Data",
+    description="Delete all saved memory data and reset the memory structure to an empty state.",
+)
+async def clear_memory() -> MemoryResponse:
+    """Clear all persisted memory data."""
+    try:
+        memory_data = clear_memory_data()
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Failed to clear memory data.") from exc
+
+    return MemoryResponse(**memory_data)
+
+
+@router.delete(
+    "/memory/facts/{fact_id}",
+    response_model=MemoryResponse,
+    summary="Delete Memory Fact",
+    description="Delete a single saved memory fact by its fact id.",
+)
+async def delete_memory_fact_endpoint(fact_id: str) -> MemoryResponse:
+    """Delete a single fact from memory by fact id."""
+    try:
+        memory_data = delete_memory_fact(fact_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=f"Memory fact '{fact_id}' not found.") from exc
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Failed to delete memory fact.") from exc
+
+    return MemoryResponse(**memory_data)
+
+
 @router.get(
     "/memory/config",
     response_model=MemoryConfigResponse,

backend/docs/MEMORY_SETTINGS_REVIEW.md

@@ -0,0 +1,39 @@
+# Memory Settings Review
+
+Use this when reviewing the Memory Settings search, filter, delete, and clear-all flow locally.
+
+## Quick Review
+
+1. Start DeerFlow locally.
+
+   ```bash
+   make dev
+   ```
+
+2. Load the sample memory fixture.
+
+   ```bash
+   python scripts/load_memory_sample.py
+   ```
+
+3. Open the app and review `Settings > Memory`.
+
+   Default local URLs:
+   - App: `http://localhost:2026`
+   - Local frontend-only fallback: `http://localhost:3000`
+
+## What To Check
+
+- Search `memory` and confirm multiple facts are matched.
+- Search `Chinese` and confirm text filtering works.
+- Search `workflow` and confirm category text is also searchable.
+- Switch between `All`, `Facts`, and `Summaries`.
+- Delete the disposable sample fact and confirm the list updates immediately.
+- Clear all memory and confirm the page enters the empty state.
+
+## Fixture Files
+
+- Sample fixture: `backend/docs/memory-settings-sample.json`
+- Default local runtime target: `backend/.deer-flow/memory.json`
+
+The loader script creates a timestamped backup automatically before overwriting an existing runtime memory file.

backend/docs/memory-settings-sample.json

@@ -0,0 +1,106 @@
+{
+  "version": "1.0",
+  "lastUpdated": "2026-03-28T10:30:00Z",
+  "user": {
+    "workContext": {
+      "summary": "Working on DeerFlow memory management UX, including local search, local filters, clear-all, and single-fact deletion in Settings > Memory.",
+      "updatedAt": "2026-03-28T10:30:00Z"
+    },
+    "personalContext": {
+      "summary": "Prefers Chinese during collaboration, but wants GitHub PR titles and bodies written in English with a Chinese translation provided alongside them.",
+      "updatedAt": "2026-03-28T10:28:00Z"
+    },
+    "topOfMind": {
+      "summary": "Wants reviewers to be able to reproduce the memory search and filter flow quickly with pre-populated sample data.",
+      "updatedAt": "2026-03-28T10:26:00Z"
+    }
+  },
+  "history": {
+    "recentMonths": {
+      "summary": "Recently contributed multiple DeerFlow pull requests covering memory, uploads, and compatibility fixes.",
+      "updatedAt": "2026-03-28T10:24:00Z"
+    },
+    "earlierContext": {
+      "summary": "Often prefers shipping smaller, reviewable changes with explicit validation notes.",
+      "updatedAt": "2026-03-28T10:22:00Z"
+    },
+    "longTermBackground": {
+      "summary": "Actively building open-source contribution experience and improving end-to-end delivery quality.",
+      "updatedAt": "2026-03-28T10:20:00Z"
+    }
+  },
+  "facts": [
+    {
+      "id": "fact_review_001",
+      "content": "User prefers Chinese for day-to-day collaboration.",
+      "category": "preference",
+      "confidence": 0.95,
+      "createdAt": "2026-03-28T09:50:00Z",
+      "source": "thread_pref_cn"
+    },
+    {
+      "id": "fact_review_002",
+      "content": "PR titles and bodies should be drafted in English and accompanied by a Chinese translation.",
+      "category": "workflow",
+      "confidence": 0.93,
+      "createdAt": "2026-03-28T09:52:00Z",
+      "source": "thread_pr_style"
+    },
+    {
+      "id": "fact_review_003",
+      "content": "User implemented memory search and filter improvements in the DeerFlow settings page.",
+      "category": "project",
+      "confidence": 0.91,
+      "createdAt": "2026-03-28T09:54:00Z",
+      "source": "thread_memory_filters"
+    },
+    {
+      "id": "fact_review_004",
+      "content": "User added clear-all memory support through the gateway memory API.",
+      "category": "project",
+      "confidence": 0.89,
+      "createdAt": "2026-03-28T09:56:00Z",
+      "source": "thread_memory_clear"
+    },
+    {
+      "id": "fact_review_005",
+      "content": "User added single-fact deletion support for persisted memory entries.",
+      "category": "project",
+      "confidence": 0.9,
+      "createdAt": "2026-03-28T09:58:00Z",
+      "source": "thread_memory_delete"
+    },
+    {
+      "id": "fact_review_006",
+      "content": "Reviewer can search for keyword memory to see multiple matching facts.",
+      "category": "testing",
+      "confidence": 0.84,
+      "createdAt": "2026-03-28T10:00:00Z",
+      "source": "thread_review_demo"
+    },
+    {
+      "id": "fact_review_007",
+      "content": "Reviewer can search for keyword Chinese to verify cross-category matching.",
+      "category": "testing",
+      "confidence": 0.82,
+      "createdAt": "2026-03-28T10:02:00Z",
+      "source": "thread_review_demo"
+    },
+    {
+      "id": "fact_review_008",
+      "content": "Reviewer can search for workflow to verify category text is included in local filtering.",
+      "category": "testing",
+      "confidence": 0.81,
+      "createdAt": "2026-03-28T10:04:00Z",
+      "source": "thread_review_demo"
+    },
+    {
+      "id": "fact_review_009",
+      "content": "Delete fact testing can target this disposable sample entry.",
+      "category": "testing",
+      "confidence": 0.78,
+      "createdAt": "2026-03-28T10:06:00Z",
+      "source": "thread_delete_demo"
+    }
+  ]
+}

backend/packages/harness/deerflow/agents/memory/__init__.py

@@ -25,6 +25,8 @@ from deerflow.agents.memory.storage import (
 )
 from deerflow.agents.memory.updater import (
     MemoryUpdater,
+    clear_memory_data,
+    delete_memory_fact,
     get_memory_data,
     reload_memory_data,
     update_memory_from_conversation,
@@ -47,6 +49,8 @@ __all__ = [
     "get_memory_storage",
     # Updater
     "MemoryUpdater",
+    "clear_memory_data",
+    "delete_memory_fact",
     "get_memory_data",
     "reload_memory_data",
     "update_memory_from_conversation",

backend/packages/harness/deerflow/agents/memory/updater.py

@@ -11,12 +11,22 @@ from deerflow.agents.memory.prompt import (
     MEMORY_UPDATE_PROMPT,
     format_conversation_for_update,
 )
-from deerflow.agents.memory.storage import get_memory_storage
+from deerflow.agents.memory.storage import create_empty_memory, get_memory_storage
 from deerflow.config.memory_config import get_memory_config
 from deerflow.models import create_chat_model
 
 logger = logging.getLogger(__name__)
 
+
+def _create_empty_memory() -> dict[str, Any]:
+    """Backward-compatible wrapper around the storage-layer empty-memory factory."""
+    return create_empty_memory()
+
+
+def _save_memory_to_file(memory_data: dict[str, Any], agent_name: str | None = None) -> bool:
+    """Backward-compatible wrapper around the configured memory storage save path."""
+    return get_memory_storage().save(memory_data, agent_name)
+
 def get_memory_data(agent_name: str | None = None) -> dict[str, Any]:
     """Get the current memory data via storage provider."""
     return get_memory_storage().load(agent_name)
@@ -26,6 +36,31 @@ def reload_memory_data(agent_name: str | None = None) -> dict[str, Any]:
     return get_memory_storage().reload(agent_name)
 
 
+def clear_memory_data(agent_name: str | None = None) -> dict[str, Any]:
+    """Clear all stored memory data and persist an empty structure."""
+    cleared_memory = _create_empty_memory()
+    if not _save_memory_to_file(cleared_memory, agent_name):
+        raise OSError("Failed to save cleared memory data")
+    return cleared_memory
+
+
+def delete_memory_fact(fact_id: str, agent_name: str | None = None) -> dict[str, Any]:
+    """Delete a fact by its id and persist the updated memory data."""
+    memory_data = get_memory_data(agent_name)
+    facts = memory_data.get("facts", [])
+    updated_facts = [fact for fact in facts if fact.get("id") != fact_id]
+    if len(updated_facts) == len(facts):
+        raise KeyError(fact_id)
+
+    updated_memory = dict(memory_data)
+    updated_memory["facts"] = updated_facts
+
+    if not _save_memory_to_file(updated_memory, agent_name):
+        raise OSError(f"Failed to save memory data after deleting fact '{fact_id}'")
+
+    return updated_memory
+
+
 def _extract_text(content: Any) -> str:
     """Extract plain text from LLM response content (str or list of content blocks).
 

backend/packages/harness/deerflow/client.py

@@ -682,6 +682,18 @@ class DeerFlowClient:
 
         return reload_memory_data()
 
+    def clear_memory(self) -> dict:
+        """Clear all persisted memory data."""
+        from deerflow.agents.memory.updater import clear_memory_data
+
+        return clear_memory_data()
+
+    def delete_memory_fact(self, fact_id: str) -> dict:
+        """Delete a single fact from memory by fact id."""
+        from deerflow.agents.memory.updater import delete_memory_fact
+
+        return delete_memory_fact(fact_id)
+
     def get_memory_config(self) -> dict:
         """Get memory system configuration.
 

backend/tests/test_client.py

@@ -674,6 +674,19 @@ class TestMemoryManagement:
             result = client.reload_memory()
         assert result == data
 
+    def test_clear_memory(self, client):
+        data = {"version": "1.0", "facts": []}
+        with patch("deerflow.agents.memory.updater.clear_memory_data", return_value=data):
+            result = client.clear_memory()
+        assert result == data
+
+    def test_delete_memory_fact(self, client):
+        data = {"version": "1.0", "facts": []}
+        with patch("deerflow.agents.memory.updater.delete_memory_fact", return_value=data) as delete_fact:
+            result = client.delete_memory_fact("fact_123")
+            delete_fact.assert_called_once_with("fact_123")
+        assert result == data
+
     def test_get_memory_config(self, client):
         config = MagicMock()
         config.enabled = True

backend/tests/test_memory_router.py

@@ -0,0 +1,72 @@
+from unittest.mock import patch
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from app.gateway.routers import memory
+
+
+def _sample_memory(facts: list[dict] | None = None) -> dict:
+    return {
+        "version": "1.0",
+        "lastUpdated": "2026-03-26T12:00:00Z",
+        "user": {
+            "workContext": {"summary": "", "updatedAt": ""},
+            "personalContext": {"summary": "", "updatedAt": ""},
+            "topOfMind": {"summary": "", "updatedAt": ""},
+        },
+        "history": {
+            "recentMonths": {"summary": "", "updatedAt": ""},
+            "earlierContext": {"summary": "", "updatedAt": ""},
+            "longTermBackground": {"summary": "", "updatedAt": ""},
+        },
+        "facts": facts or [],
+    }
+
+
+def test_clear_memory_route_returns_cleared_memory() -> None:
+    app = FastAPI()
+    app.include_router(memory.router)
+
+    with patch("app.gateway.routers.memory.clear_memory_data", return_value=_sample_memory()):
+        with TestClient(app) as client:
+            response = client.delete("/api/memory")
+
+    assert response.status_code == 200
+    assert response.json()["facts"] == []
+
+
+def test_delete_memory_fact_route_returns_updated_memory() -> None:
+    app = FastAPI()
+    app.include_router(memory.router)
+    updated_memory = _sample_memory(
+        facts=[
+            {
+                "id": "fact_keep",
+                "content": "User likes Python",
+                "category": "preference",
+                "confidence": 0.9,
+                "createdAt": "2026-03-20T00:00:00Z",
+                "source": "thread-1",
+            }
+        ]
+    )
+
+    with patch("app.gateway.routers.memory.delete_memory_fact", return_value=updated_memory):
+        with TestClient(app) as client:
+            response = client.delete("/api/memory/facts/fact_delete")
+
+    assert response.status_code == 200
+    assert response.json()["facts"] == updated_memory["facts"]
+
+
+def test_delete_memory_fact_route_returns_404_for_missing_fact() -> None:
+    app = FastAPI()
+    app.include_router(memory.router)
+
+    with patch("app.gateway.routers.memory.delete_memory_fact", side_effect=KeyError("fact_missing")):
+        with TestClient(app) as client:
+            response = client.delete("/api/memory/facts/fact_missing")
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Memory fact 'fact_missing' not found."

backend/tests/test_memory_updater.py

@@ -1,7 +1,12 @@
 from unittest.mock import MagicMock, patch
 
 from deerflow.agents.memory.prompt import format_conversation_for_update
-from deerflow.agents.memory.updater import MemoryUpdater, _extract_text
+from deerflow.agents.memory.updater import (
+    MemoryUpdater,
+    _extract_text,
+    clear_memory_data,
+    delete_memory_fact,
+)
 from deerflow.config.memory_config import MemoryConfig
 
 
@@ -138,6 +143,57 @@ def test_apply_updates_preserves_threshold_and_max_facts_trimming() -> None:
     assert result["facts"][1]["source"] == "thread-9"
 
 
+def test_clear_memory_data_resets_all_sections() -> None:
+    with patch("deerflow.agents.memory.updater._save_memory_to_file", return_value=True):
+        result = clear_memory_data()
+
+    assert result["version"] == "1.0"
+    assert result["facts"] == []
+    assert result["user"]["workContext"]["summary"] == ""
+    assert result["history"]["recentMonths"]["summary"] == ""
+
+
+def test_delete_memory_fact_removes_only_matching_fact() -> None:
+    current_memory = _make_memory(
+        facts=[
+            {
+                "id": "fact_keep",
+                "content": "User likes Python",
+                "category": "preference",
+                "confidence": 0.9,
+                "createdAt": "2026-03-18T00:00:00Z",
+                "source": "thread-a",
+            },
+            {
+                "id": "fact_delete",
+                "content": "User prefers tabs",
+                "category": "preference",
+                "confidence": 0.8,
+                "createdAt": "2026-03-18T00:00:00Z",
+                "source": "thread-b",
+            },
+        ]
+    )
+
+    with (
+        patch("deerflow.agents.memory.updater.get_memory_data", return_value=current_memory),
+        patch("deerflow.agents.memory.updater._save_memory_to_file", return_value=True),
+    ):
+        result = delete_memory_fact("fact_delete")
+
+    assert [fact["id"] for fact in result["facts"]] == ["fact_keep"]
+
+
+def test_delete_memory_fact_raises_for_unknown_id() -> None:
+    with patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()):
+        try:
+            delete_memory_fact("fact_missing")
+        except KeyError as exc:
+            assert exc.args == ("fact_missing",)
+        else:
+            raise AssertionError("Expected KeyError for missing fact id")
+
+
 # ---------------------------------------------------------------------------
 # _extract_text — LLM response content normalization
 # ---------------------------------------------------------------------------