bytedance/deer-flow · error · MemoryStorageCorruption

Invalid canonical fact {fact_path}: {exc}

Error message

Invalid canonical fact {fact_path}: {exc}

What it means

Error "Invalid canonical fact {fact_path}: {exc}" thrown in bytedance/deer-flow.

Source

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

    @staticmethod
    def _validate_loaded_fact(
        fact: dict[str, Any],
        fact_path: Path,
        *,
        user_id: str | None,
        agent_name: str,
    ) -> dict[str, Any]:
        if str(fact.get("id")) != fact_path.stem:
            raise MemoryStorageCorruption(f"Fact id mismatch for {fact_path}")
        expected_scope = _scope_dict(user_id, agent_name)
        actual_scope = fact.get("scope")
        scope_matches = isinstance(actual_scope, dict) and actual_scope.get("userId") == user_id and isinstance(actual_scope.get("agentName"), str) and actual_scope["agentName"].lower() == agent_name.lower()
        if not scope_matches:
            raise MemoryStorageCorruption(f"Fact scope mismatch for {fact_path}: expected {expected_scope!r}, found {fact.get('scope')!r}")
        try:
            return _normalize_fact(fact, scope=copy.deepcopy(actual_scope))
        except ValueError as exc:
            raise MemoryStorageCorruption(f"Invalid canonical fact {fact_path}: {exc}") from exc

    def _load_agent_facts(self, path: Path, agent_name: str | None, *, user_id: str | None) -> list[dict[str, Any]]:
        if agent_name is None:
            return []
        facts: list[dict[str, Any]] = []
        for fact_path in sorted(agent_facts_directory(path, agent_name).glob("**/*.md")):
            fact = _parse_fact_markdown(fact_path)
            facts.append(self._validate_loaded_fact(fact, fact_path, user_id=user_id, agent_name=agent_name))
        # Shard directories are an internal layout detail and must not change
        # the stable fact order observed by callers.
        return sorted(facts, key=lambda fact: str(fact["id"]))

    def _read_fact(self, path: Path, fact_id: str, *, user_id: str | None, agent_name: str) -> tuple[dict[str, Any] | None, Path]:
        fact_path = fact_file_path(path, fact_id, agent_name=agent_name)
        if not fact_path.exists():
            return None, fact_path
        fact = _parse_fact_markdown(fact_path)
        return self._validate_loaded_fact(fact, fact_path, user_id=user_id, agent_name=agent_name), fact_path

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Fix the validation issue named in the exception (field type or value) in the fact file.
2. Delete the invalid fact file and recreate the fact via the memory API.

When it happens

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