bytedance/deer-flow · error · MemoryStorageCorruption

Legacy facts in {path} require explicit migrate(user_id=...,

Error message

Legacy facts in {path} require explicit migrate(user_id=..., agent_name=...)

What it means

Error "Legacy facts in {path} require explicit migrate(user_id=..., agent_name=...)" thrown in bytedance/deer-flow.

Source

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

        )
        if legacy_memory is not None:
            legacy_path.unlink(missing_ok=True)
        return True, from_version, notifications

    def _document_from_memory_file(
        self,
        memory_file: dict[str, Any],
        path: Path,
        agent_name: str | None,
        *,
        user_id: str | None,
        allow_legacy_facts: bool = False,
    ) -> dict[str, Any]:
        """Build the compatibility document without persisting facts in JSON."""
        legacy_facts = memory_file.get("facts")
        contains_owned_legacy_facts = isinstance(legacy_facts, dict) or (isinstance(legacy_facts, list) and bool(legacy_facts))
        if contains_owned_legacy_facts and not allow_legacy_facts:
            raise MemoryStorageCorruption(f"Legacy facts in {path} require explicit migrate(user_id=..., agent_name=...)")
        if isinstance(legacy_facts, list):
            facts = copy.deepcopy(legacy_facts) if agent_name is not None else []
        elif isinstance(legacy_facts, dict):
            facts = []
            if agent_name is not None:
                for fact_id, entry in legacy_facts.items():
                    if not isinstance(entry, dict) or not isinstance(entry.get("path"), str):
                        raise MemoryStorageCorruption(f"Invalid legacy manifest entry for fact {fact_id!r}")
                    fact_path = _safe_relative_path(path.parent, entry["path"], label="legacy fact")
                    fact = _parse_fact_markdown(fact_path)
                    if str(fact.get("id")) != str(fact_id):
                        raise MemoryStorageCorruption(f"Legacy manifest id mismatch for fact {fact_id!r}")
                    if entry.get("contentHash") and entry.get("contentHash") != _content_hash(fact_path.read_bytes()):
                        raise MemoryStorageCorruption(f"Hash mismatch for canonical fact {fact_id!r}")
                    facts.append(fact)
        elif legacy_facts is None:
            facts = self._load_agent_facts(path, agent_name, user_id=user_id)
        else:

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Call migrate with explicit user_id and agent_name arguments.
2. Programmatic migration only; legacy facts are not auto-migrated without scope.

When it happens

Trigger: Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py:948 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/2bb462f232f9ee3a. Report an issue: GitHub.