bytedance/deer-flow · error · ValueError

memory_data.facts is required for an agent full save

Error message

memory_data.facts is required for an agent full save

What it means

Error "memory_data.facts is required for an agent full save" thrown in bytedance/deer-flow.

Source

Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py:1080

        user_id: str | None = None,
        expected_revision: int | None = None,
    ) -> bool:
        """Compatibility full replacement, diffed into per-fact operations.

        This API must scan the selected agent to determine which omitted facts
        are deletions, but the commit writes only new/changed/deleted facts.
        Repository callers should prefer ``apply_changes`` to avoid even that
        full comparison scan.
        """
        path = self._get_memory_file_path(agent_name, user_id=user_id)
        key = self._cache_key(agent_name, user_id=user_id)
        lock_path = path.parent / ".memory.lock"
        notifications: list[RetrievalNotification] = []
        try:
            if not isinstance(memory_data, dict):
                raise ValueError("memory_data must be an object")
            if agent_name is not None and "facts" not in memory_data:
                raise ValueError("memory_data.facts is required for an agent full save")
            facts_raw = memory_data.get("facts", [])
            if not isinstance(facts_raw, list):
                raise ValueError("memory_data.facts must be a list")
            if any(not isinstance(fact, dict) for fact in facts_raw):
                raise ValueError("memory_data.facts must contain only fact objects")
            if agent_name is None and facts_raw:
                raise ValueError("agent_name is required to persist facts")
            with self._scope_lock(key), _process_file_lock(lock_path, float(getattr(self._config, "file_lock_timeout_seconds", 10))):
                self._recover_if_needed(path)
                ids = [str(fact.get("id") or "") for fact in facts_raw]
                if len(ids) != len(set(ids)):
                    raise ValueError("Duplicate fact ids are not allowed")
                old_ids = set(self._agent_entries(path, agent_name, user_id=user_id)) if agent_name is not None else set()
                summaries = None
                if agent_name is None:
                    summaries = {"user": memory_data.get("user", {}), "history": memory_data.get("history", {})}
                _, notifications = self._commit_changes_locked(
                    path,

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Include a facts array in memory_data for a full agent save.
2. Use a partial update API if you do not intend to replace all facts.

When it happens

Trigger: Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py:1080 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/660d657b1430a986. Report an issue: GitHub.