bytedance/deer-flow · error · MemoryStorageCorruption

Legacy facts in {path} must be a list or mapping

Error message

Legacy facts in {path} must be a list or mapping

What it means

Error "Legacy facts in {path} must be a list or mapping" thrown in bytedance/deer-flow.

Source

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

        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:
            raise MemoryStorageCorruption(f"Legacy facts in {path} must be a list or mapping")
        result = {key: copy.deepcopy(value) for key, value in memory_file.items() if key != "facts"}
        result.setdefault("revision", 0)
        result["facts"] = facts
        return result

    def _read_document(self, path: Path, agent_name: str | None, *, user_id: str | None) -> dict[str, Any]:
        memory_file = self._load_memory_file(path)
        if memory_file is None:
            result = create_empty_memory()
            result["facts"] = self._load_agent_facts(path, agent_name, user_id=user_id)
            return result
        return self._document_from_memory_file(memory_file, path, agent_name, user_id=user_id)

    def load(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
        path = self._get_memory_file_path(agent_name, user_id=user_id)
        key = self._cache_key(agent_name, user_id=user_id)
        journal_path = path.parent / ".memory.journal.json"
        legacy_path = self._legacy_agent_memory_path(path, agent_name) if agent_name is not None else None

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Convert the legacy facts file to a JSON list or mapping before migrating.
2. Fix the file's top-level JSON structure and retry migration.

When it happens

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