eb97327ddf
* fix(memory): reject duplicate fact ids in imports regardless of entry order A backup containing two entries for the same fact id was accepted or rejected depending only on their order. The duplicate check in _commit_changes_locked consulted the map of prepared writes, but an entry whose normalized content matches the stored fact is skipped from that map - so an unchanged entry followed by an edited duplicate passed the check while the reverse order raised, and the saved snapshot ended up with whichever entry came last. Track every incoming id in a seen-set for duplicate detection, before the unchanged-entry skip. The saved snapshot now survives the rejection in both orders. Fixes #8150 * fix(memory): validate duplicate import ids before capacity selection Copilot review follow-up on #8153: the storage-level duplicate guard runs after _select_for_capacity, and the capacity policy can drop one of two same-id entries (e.g. lower-confidence copies trimmed to max_facts) - the duplicate then never reaches the guard and the import outcome still depends on entry order. Validate all normalized incoming ids in import_memory_data before capacity selection. The storage-level guard stays as defense in depth. Regression test with max_facts=10 and 9 distinct high-confidence facts plus two same-id copies. * fix(memory): surface duplicate fact id errors with their own detail willem-bd review on #8153, three follow-ups: 1. P2: the bare ValueError fell through to the router's generic catch, so POST /api/memory/import answered with the facts-array message even when every fact had non-empty content. Add MemoryDuplicateFactIdError (same type as #8151) at the manager boundary and map it to its own 400 detail that names the duplicated id; router test asserts the exact detail. 2. P3: the duplicate check lived inside the apply_changes-override branch, so the base MemoryStorage save() path bypassed both guards. Move it before the branch split, right after normalize_memory_data, matching #8151's validate-before-capacity posture. 3. P3: parametrize the order-dependence regression over the default bucket (agent_name=None) and "researcher", and assert the seeded snapshot survives the rejection in both orders. * test(memory): pin the storage duplicate guard and fix the no-op assertion willem-bd review follow-ups on #8153: 1. The snapshot-survival assertion compared storage.load against get_memory_data, which is itself storage.load - both reads happened after the rejected import, so a regression that partially applied the duplicate would pass. Capture the seeded snapshot before the rejected import and compare against it. 2. The updater gate rejects import duplicates before storage is touched, so nothing exercised the storage-level guard in _commit_changes_locked with an unchanged duplicate first - reverting it would keep the suite green. Add a direct apply_changes regression test; verified it fails with the guard removed. * style(memory): apply ruff fixes after #8151 merge resolution * test(memory): assert untouched store in the storage-guard pin; facade import willem-bd review follow-ups on #8153: 1. The storage-guard regression test pinned rejection but not the untouched-store half: capture the seeded snapshot right after seeding and assert storage.load still equals it after the rejection, so a regression that partially applies the first entry before raising fails. 2. The router regression test imported MemoryDuplicateFactIdError from the manager module directly; use the package-facade import consistent with the other manager-error usage (the symbol is already re-exported from deerflow.agents.memory since #8151). * test(memory): drop the mock router duplicate-id test ShenAC-SAC review on #8153: #8151 already drives the real import route with duplicate IDs and asserts the same 400 response plus an unchanged snapshot, and the mock test's docstring implied a detail the assertion did not check. The direct apply_changes() regression is kept. Also removes the blank line after the docstring that tripped ruff format --check on the repo-pinned Ruff version. * test(memory): remove the orphaned mock-router test body ShenAC-SAC review: my earlier deletion removed the function definition and docstring but left the test body running inside test_clear_route_keeps_working_for_windows_reserved_agent_name. Remove the whole block and the now-unused MemoryDuplicateFactIdError import; #8151 already covers the duplicate-ID response through the real import route.
English | 中文 | 日本語 | Français | Русский | Português | 한국어
On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥
DeerFlow (Deep Exploration and Efficient Research Flow) is an open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to do almost anything — powered by extensible skills.
https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
Note
DeerFlow 2.0 is a ground-up rewrite. It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the
1.xbranch — contributions there are still welcome. Active development has moved to 2.0.
Official Website
Learn more and see real demos on our official website. The landing-page case studies open as allowlisted, read-only showcases without requiring a sign-in.
Sister Projects
- LLM Space - Meet our secret weapon behind DeerFlow — one desktop tool to prototype agent ideas, inspect each harness step, replay failures, and benchmark performance.
Coding Plan from ByteDance Volcengine
- We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow
- Learn more
- 中国大陆地区的开发者请点击这里
InfoQuest
DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus — InfoQuest (supports free online experience)
One-Line Agent Setup
If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence:
Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide.
Quick Start
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup # interactive wizard: writes config.yaml and .env (about 2 minutes)
Then start DeerFlow with Docker (recommended) or run it locally:
# Docker
make docker-init # pull the sandbox image (once, or when the image updates)
make docker-start # start services
# Local development
make check # verifies Node.js 22+, pnpm, uv, nginx
make install
make dev
Open http://localhost:2026.
- All configuration options, providers and manual setup: Configuration
- Docker details, sizing, upgrades, startup modes and production deployment: Running the Application
- Running on a server or exposing it beyond localhost: read the Security Notice first
From Deep Research to Super Agent Harness
DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated.
That told us something important: DeerFlow wasn't just a research tool. It was a harness — a runtime that gives agents the infrastructure to actually get work done.
So we rebuilt it from scratch.
DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.
Use it as-is. Or tear it apart and make it yours.
Guides
Each guide is the full reference for its topic. Open the one you need.
| Topic | Guide |
|---|---|
Models, providers, config.yaml, environment variables |
Configuration |
| Docker, local development, upgrades, production deployment | Running the Application |
| Sandbox modes, file system, uploads and outputs | Sandbox |
| Skills, built-in tools, script workflows, Claude Code integration | Skills & Tools |
| MCP servers | MCP Server |
| Sub-agents and task delegation | Sub-Agents, Tool restrictions |
| Long-term memory | Long-Term Memory |
| Session goals, context compaction, task notes, evidence-based decisions | Context, Goals and Agent Decisions |
| Private knowledge retrieval (RAGFlow) | Private Knowledge Retrieval |
| Agentic browser control | Agentic Browser Control |
| Projects, instructions, document shelf | Projects |
| Scheduled tasks | Scheduled Tasks |
| Feishu, Slack, Telegram, Discord, DingTalk and other IM channels | IM Channels |
| Token usage dashboard, workspace, chat archive | Workspace UI |
| Terminal workbench | Terminal Workbench (TUI) |
| Personal access tokens, stream actions, embedded Python client | API Access and Python Client |
| Trace correlation, LangSmith, Langfuse, Monocle | Tracing and Observability |
| Deployment risks, admin model, security recommendations | Security Notice |
Recommended Models
DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:
- Long context windows (100k+ tokens) for deep research and multi-step tasks
- Reasoning capabilities for adaptive planning and complex decomposition
- Multimodal inputs for image understanding and video comprehension
- Strong tool-use for reliable function calling and structured outputs
More Documentation
- Install.md - Setup instructions written for coding agents
- Configuration Reference - Every
config.yamloption - Backend Architecture - Backend architecture and API reference
- Architecture Overview - How the services fit together
- Contributing Guide - Development environment, workflow and tests
- Changelog - Release notes
⚠️ Security Notice
DeerFlow can execute commands and read and write files. It is designed to run in a local trusted environment, and a Gateway admin account is equivalent to code execution on the host. Before you deploy it on a server or expose it to a network, read the full Security Notice and SECURITY.md.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for development setup, workflow, and guidelines.
License
This project is open source and available under the MIT License.
Acknowledgments
DeerFlow is built upon the incredible work of the open-source community. We are deeply grateful to all the projects and contributors whose efforts have made DeerFlow possible. Truly, we stand on the shoulders of giants.
We would like to extend our sincere appreciation to the following projects for their invaluable contributions:
- LangChain: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
- LangGraph: Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows.
These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations.
Key Contributors
A heartfelt thank you goes out to the core authors of DeerFlow, whose vision, passion, and dedication have brought this project to life:
Your unwavering commitment and expertise have been the driving force behind DeerFlow's success. We are honored to have you at the helm of this journey.