Reference

Every name, key, string, and test anchor behind database.checkpoint_channel_mode. This page is for looking things up, not for learning the model; start with Channel Modes if you need the concepts.

Evidence column values are repo-relative path:line references using the aliases below. A fact that appears here is traceable to one of those lines.

The pinned dependency set referenced by the defect table is langgraph 1.2.9, langgraph-checkpoint 4.2.0, and langgraph-checkpoint-postgres 3.1.2.

Configuration keys

Every database.* key related to checkpoints, with the constraint the loader actually enforces. “Restart” means the running process captured the value at startup — frozen into process state, compiled into a channel table, or bound when a singleton such as the checkpointer and its history cache was constructed — so an edit does not take effect until that process restarts.

What each key affects

• database.checkpoint_channel_mode selects how the messages channel is stored: whole-value checkpoints (full) or a LangGraph DeltaChannel sentinel plus per-step writes (delta). It affects every read and write of a thread.
• database.checkpoint_delta.snapshot_frequency is the cadence at which delta mode writes a full messages snapshot every N per-step writes. Higher means smaller checkpoints and slower materialization. It is ignored in full mode.
• database.checkpoint_graph_cache.accessor_graph_max caps the compiled thread-state accessor graphs a process caches, keyed per assistant, channel mode, and snapshot cadence. Unlike the mode and cadence it is not restart-required, because a different cap only changes when the cache evicts, never graph semantics.
• database.checkpoint_cache.* configures the delta-mode materialized-history cache only. It is performance-only and never frozen — no correctness invariant requires cross-process agreement, and results are identical with it disabled — but it is not hot-reloadable: the cache object is constructed with the checkpointer at startup (deps:463, asyncprov:250-254), inside a database section that reload registers as startup-only (reload:47), so changing any of these fields needs a restart. The memory backend is bounded by max_entries, the redis backend by ttl_seconds and the server’s own maxmemory policy.
• database.backend selects which saver serves the threads (InMemorySaver, SQLite, or Postgres). Mode semantics live in the compiled channel table rather than in the saver, so both modes work on all three backends.

The verbatim Field(description=...) text for the two frozen keys is worth reading once, because it states the cross-process rule:

"Checkpoint representation for accumulating channels. 'full' preserves full-value message checkpoints;
'delta' uses LangGraph DeltaChannel for messages. Restart is required, and all processes sharing one
checkpoint database must use the same value."

"DeltaChannel snapshot cadence: a full messages snapshot is stored every N per-step writes
(higher = smaller checkpoints, slower materialization). Restart is required, and all processes
sharing one checkpoint database must use the same value."

Validation

Deprecated flat key and migration warnings

The old top-level database.checkpoint_delta_snapshot_frequency is still honored by the pydantic @model_validator(mode="before") named _migrate_legacy_snapshot_frequency. It logs one of exactly three strings, all operator-visible:

Environment variables

No environment variable selects the checkpoint mode or its cadence. Both come only from config.yaml. The only mode-feature environment variables are the history-cache redis URL fallbacks (DEER_FLOW_CHECKPOINT_CACHE_REDIS_URL, then REDIS_URL, then redis://localhost:6379/0) at cacheprov:19-23. $VAR interpolation in config values is resolved centrally by AppConfig.resolve_env_variables() before DatabaseConfig is constructed, so DatabaseConfig itself does no environment processing (dbcfg:13-22, appcfg:442).

Config version

The schema change shipped with config_version 27; config.example.yaml is currently config_version: 49 and a missing version counts as 0 (example:23, appcfg:531-575). An outdated config.yaml logs:

Your config.yaml (version %d) is outdated — the latest version is %d. Run `make config-upgrade` to merge new fields into your config.

make config-upgrade merges the new key with the safe default full (appcfg:570-575, backend/tests/test_config_version.py:151-203). See Configuration for the general upgrade flow.

Constants and keys

Marker semantics, in one place: inject_checkpoint_mode(config, mode) always sets config["configurable"]["__deerflow_checkpoint_channel_mode"]. In delta mode it additionally sets config["metadata"]["deerflow_checkpoint_channel_mode"] = "delta"; in full mode it removes that metadata key, so absence means full and pre-feature checkpoints need no migration (cmode:81-88). The snapshot cadence is deliberately not stamped into checkpoint metadata, because the mode marker contract and the full-to-delta migration semantics are unchanged by the frequency value (cmode:53-60).

Exceptions and HTTP status

Verbatim messages raised by the mode machinery and its guards:

HTTP status mapping

Only the threads router imports these errors. It registers the gate tuple _CHECKPOINT_MODE_ERRORS = (CheckpointModeMismatchError, CheckpointModeReconfigurationError) (threads:82) and maps it as follows. Bodies are FastAPI’s default {"detail": "<string>"}.

The router states the rationale: a mismatch means the thread’s persisted checkpoints conflict with the process’s frozen mode (operator-actionable, 409); a reconfiguration means the process itself is mid mode-flip (transient, 503) (threads:99-102). The 503 half is defensive — nothing in these routes can raise it. The freeze helpers are called only by Gateway startup (deps:451-452), agent:835,839, and client:230-231, and no state, history, or thread route builds an agent: a checkpoint_channel_mode edit is injected over by the run worker (worker:1018-1019, preferred at agent:831-835) and ignored until a restart, and a snapshot_frequency edit makes the next run fail with the message (worker:1450-1462) instead of returning a status.

Routes that return 409

Routes where the mismatch fails asynchronously

Routes with no mode mapping

No reporting surface

No health, readiness, features, capabilities, or console field reports the mode or cadence. No response model, header, or event field carries it either: the only custom SSE headers are Cache-Control, Connection, X-Accel-Buffering, and Content-Location. The mode is consumed server-side only, through app.state.checkpoint_channel_mode, app.state.checkpoint_snapshot_frequency, and RunContext (deps:451-452,767-768, services:1093,1283-1312). A latent exception is that the response metadata on GET /api/threads/{thread_id} and on POST /api/threads/{thread_id}/history strips other internal keys but not the delta marker or counters_since_delta_snapshot, so those can pass through to a client (threads:1308-1315, threads:1890-1900). The SSE metadata frame carries only {"run_id", "thread_id"} (worker:1067-1074). See Observability.

Public symbols

Import paths a consumer may rely on. Everything listed here is a Python import; the route contracts are in the HTTP status mapping section above.

Internal symbols

These are implementation details. Do not import them, and do not build on their names or shapes.

Load-bearing tests

Tests a reader can run or cite as the executable contract. All paths are under backend/tests/.

Mode gate, freezing, and configuration

• test_checkpoint_mode.py (freeze, detection, gate) — the module named as the mode gate in backend/packages/harness/deerflow/runtime/AGENTS.md:133
• test_checkpoint_mode.py::test_yaml_mode_change_is_rejected_when_graph_is_reconstructed
• test_checkpoint_mode.py::test_delta_mode_accepts_plain_full_checkpoint
• test_checkpoint_mode.py::test_gateway_runtime_rejects_mode_different_from_frozen_process
• test_threads_checkpoint_mode.py (router-level mode behaviour)
• test_threads_checkpoint_mode.py::test_delta_snapshot_frequency_controls_snapshot_cadence
• test_gateway_checkpoint_mode.py (dual-mode end-to-end parity)
• test_app_config_reload.py::test_checkpoint_channel_mode_rejects_unknown_value
• test_config_version.py (config-version migration)

Materialization, storage shape, and migration

• test_delta_channel_checkpointers.py::test_full_to_delta_migration_replays_on_same_thread
• test_delta_channel_checkpointers.py::test_materialization_is_deterministic_and_message_ids_are_stable
• test_delta_channel_checkpointers.py::test_delta_storage_shape_and_snapshot_cadence
• test_delta_channel_checkpointers.py::test_non_delta_writers_preserve_delta_messages_and_markers
• test_delta_channel_checkpointers.py::test_long_chain_history_survives_pagination
• test_delta_channel_checkpointers.py::test_parallel_superstep_replay_matches_live_write_order
• test_delta_channel_state.py::test_mode_selects_expected_state_schema
• test_delta_channel_state.py::test_compiled_delta_graph_bakes_configured_snapshot_frequency
• test_delta_channel_state.py::test_production_message_forms_keep_assigned_ids_across_delta_replay
• test_delta_channel_state.py::test_delta_normalization_compiles_stable_channel_without_mutating_middleware

test_long_chain_history_survives_pagination and test_parallel_superstep_replay_matches_live_write_order assert the correct contract and trigger-skip while the pinned dependency still has the defect; they are the gates that flip live on a dependency bump.

History cache

• test_cached_history_saver.py::test_composition_matches_full_walk_and_avoids_it
• test_cached_history_saver.py::test_latest_config_caches_under_resolved_checkpoint_id
• test_cached_history_saver.py::test_recursive_resolve_caches_intermediate_levels
• test_cached_history_saver.py::test_deep_cold_chain_delegates_one_inner_walk_at_depth_limit
• test_cached_history_saver.py::test_cold_resolve_never_delegates_to_inner_history
• test_cached_history_saver.py::test_sync_cold_resolve_never_delegates_to_inner_history
• test_cached_history_saver.py::test_snapshot_parent_composes_without_parent_history_lookup
• test_cached_history_saver.py::test_root_checkpoint_history_is_empty_writes
• test_cached_history_saver.py::test_eviction_falls_back_to_walk_but_stays_correct
• test_cached_history_saver.py::test_sync_path_matches_async
• test_cached_history_saver.py::test_stats_expose_composition_counters
• test_cached_history_saver.py::test_adelete_thread_purges_only_that_threads_cache_entries
• test_cached_history_saver.py::test_sync_delete_thread_purges_cache_entries
• test_cached_history_saver.py::test_prune_purges_rewritten_threads_cache_entries
• test_cached_history_saver.py::test_delete_for_runs_delegates_without_cache_purge
• test_cached_history_saver_integration.py::test_sequential_run_composes_without_inner_walks
• test_cached_history_saver_integration.py::test_cache_disabled_parity
• test_cached_history_saver_integration.py::test_branch_divergence_no_cross_contamination
• test_cached_history_saver_integration.py::test_interrupt_resume_appended_head_writes
• test_cached_history_saver_integration.py::test_eviction_only_costs_performance
• test_cached_history_saver_integration.py::test_rollback_supersede_does_not_pollute
• test_cached_history_saver_integration.py::test_full_to_delta_migration_under_cache_states

Resume linearization and rollback

• test_run_worker_delta_resume.py::test_linearizes_a_delta_resume_onto_the_head
• test_run_worker_delta_resume.py::test_linearization_restores_all_selected_state_and_clears_newer_channels
• test_run_worker_delta_resume.py::test_linearized_resume_preserves_selected_checkpoint_agent_binding
• test_run_worker_delta_resume.py::test_regenerating_in_a_branched_thread_does_not_resurrect_the_old_answer
• test_run_worker_delta_resume.py::test_run_agent_streams_from_the_linearized_delta_resume
• test_run_worker_delta_resume.py::test_run_agent_serializes_resume_preparation_with_checkpoint_writes
• test_run_worker_delta_resume.py::test_cancelled_delta_resume_rolls_back_to_pre_linearization_head
• test_run_worker_delta_resume.py::test_full_mode_keeps_the_fork
• test_run_worker_delta_resume.py::test_ordinary_run_without_a_checkpoint_selector_is_untouched
• test_run_worker_delta_resume.py::test_selecting_the_head_is_already_linear
• test_run_worker_delta_resume.py::test_unmaterializable_resume_state_fails_closed
• test_run_worker_rollback.py::test_rollback_linearizes_delta_restore_onto_cancelled_head
• test_run_worker_rollback.py::test_rollback_linearizes_delta_restore_sqlite_reopen
• test_run_worker_rollback.py::test_rollback_restores_pre_run_pending_writes_for_delta_checkpoints
• test_run_worker_rollback.py::test_rollback_preserves_middleware_contributed_channels[delta]
• test_run_worker_rollback.py::test_rollback_preserves_agent_binding_for_manual_compaction[delta]
• test_run_worker_rollback.py::test_run_agent_marks_rollback_unusable_when_capture_fails

Retention

• test_checkpoint_retention_contract.py::test_growth_baseline_full_vs_delta
• test_checkpoint_retention_contract.py::test_deleting_branch_ancestor_breaks_lineage_loudly
• test_checkpoint_retention_contract.py::test_deleting_explicit_resume_target_breaks_resume
• test_checkpoint_retention_contract.py::test_pending_writes_are_retained_state_not_garbage
• test_checkpoint_retention_contract.py::test_leaf_duration_checkpoint_deletion_is_safe
• test_checkpoint_retention_contract.py::test_leaf_sibling_branch_deletion_is_safe

Patches

• test_checkpoint_patches.py::test_binop_overwrite_patch_is_active
• test_checkpoint_patches.py::test_binop_overwrite_patch_stands_down_when_upstream_fixed

Pinned upstream defects

State at the pinned set (langgraph 1.2.9, langgraph-checkpoint 4.2.0, langgraph-checkpoint-postgres 3.1.2). Each local test asserts the correct contract and trigger-skips while the defect is present, so a later dependency bump flips it into a live gate; the buggy behaviour is never asserted as correct.

See Operating Checkpoints for what the remaining patch does and how the dependency floor is enforced, and Troubleshooting for the symptoms each defect produces for a user.

Change log (June to September 2026)

Pull requests whose changelog entries concern dual-mode checkpoint storage. English entries under ## [Unreleased] accumulate toward milestone 2.1.0; the ## [2.0.0] entries are from the 2026-06-15 release. The section column names the changelog section each entry sits under.

No entry in this list records a change to the mode default, which has been full throughout.

The #4292 row quotes the released changelog entry verbatim. Its “near-linear” wording describes the per-step representation; retained storage still adds up to O(N²/K + N) with K = snapshot_frequency, because every periodic snapshot holds the whole growing list — see Checkpoints and Delta Channels.