bytedance/deer-flow · error · MemoryStorageCorruption

Fact id mismatch for {fact_path}

Error message

Fact id mismatch for {fact_path}

What it means

Error "Fact id mismatch for {fact_path}" thrown in bytedance/deer-flow.

Source

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

                if action == "upsert":
                    self._retrieval.upsert(copy.deepcopy(value), scope=scope, path=fact_path or "")
                else:
                    self._retrieval.remove(str(value), scope=scope)
            except Exception:
                logger.exception("Retrieval notification failed for %s", value)
                with self._cache_lock:
                    self._retrieval_dirty_scopes.add(self._cache_key(agent_name, user_id=user_id))

    @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

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Align the fact's id field with its filename, or rename the file to match the id.
2. Re-save the fact through the memory API to restore consistency.

When it happens

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