mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-07-31 02:15:59 +00:00
b990da785f
* feat(memory): add guaranteed injection for correction facts with graceful fallback When the token budget is tight, high-value facts (e.g. user corrections) can be silently evicted by lower-priority regular facts. This change: - Introduces configurable 'guaranteed_categories' (default: [correction]) whose facts draw from a separate 'guaranteed_token_budget', ensuring they are never dropped due to budget pressure. - Adds a graceful fallback to confidence-only ranking when the guaranteed-category path raises an unexpected exception. - Refactors fact selection into a header-agnostic helper (_select_fact_lines) with explicit token accounting in the caller, eliminating double-counting of separators. - Emits a single 'Facts:' header regardless of whether both guaranteed and regular facts are present. - Extends the final safety truncation limit to account for the additional guaranteed budget so guaranteed facts survive end-to-end. * refactor(memory): address review feedback on guaranteed injection - Restore strict break-on-overflow in `_select_fact_lines` to preserve the caller's confidence-ordered ranking; add a regression test locking in the invariant that a shorter lower-confidence fact never slips ahead of a skipped higher-confidence one. - Account for the inter-group `\n` separator between guaranteed and regular fact blocks in the regular budget (1-token precision fix). - Clarify docstrings on `format_memory_for_injection` and `MemoryConfig.guaranteed_token_budget` to distinguish the common *displacement* case (total stays within `max_tokens`) from the rarer *additive* case (safety-truncation ceiling raised when guaranteed lines alone would overflow). * fix(memory): address P1 safety truncation + P2s from review - Structure-aware safety truncation: Facts block is now a protected suffix so guaranteed-category facts can never be silently discarded by a prefix-cut on overflow. Only the preceding (user/history) sections are eligible for truncation. - Extend the same protected-suffix treatment to the except/fallback path by returning fact lines alongside the formatted section from _fallback_format_facts, avoiding string parsing. - Single inter-section separator: facts section no longer embeds its own leading \n\n; the final "\n\n".join(sections) is the single source of truth for section-to-section spacing. - Bare string for guaranteed_categories now raises TypeError instead of silently iterating single characters. - Category-less / malformed facts no longer default-promote into the guaranteed "context" pool — only facts with an explicit category field qualify. - Lift valid_facts pre-filter outside the try so the fallback path reuses it instead of re-doing validation work. - MemoryConfigResponse + DeerFlowClient.get_memory_config now expose guaranteed_categories / guaranteed_token_budget. - config.example.yaml: document the two new fields and bump config_version from 12 to 13. - Add regression tests for every finding. --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
122 lines
4.4 KiB
Python
122 lines
4.4 KiB
Python
"""Configuration for memory mechanism."""
|
|
|
|
from typing import Literal
|
|
|
|
from pydantic import BaseModel, Field
|
|
|
|
|
|
class MemoryConfig(BaseModel):
|
|
"""Configuration for global memory mechanism."""
|
|
|
|
enabled: bool = Field(
|
|
default=True,
|
|
description="Whether to enable memory mechanism",
|
|
)
|
|
storage_path: str = Field(
|
|
default="",
|
|
description=(
|
|
"Path to store memory data. "
|
|
"If empty, defaults to per-user memory at `{base_dir}/users/{user_id}/memory.json`. "
|
|
"Absolute paths are used as-is and opt out of per-user isolation "
|
|
"(all users share the same file). "
|
|
"Relative paths are resolved against `Paths.base_dir` "
|
|
"(not the backend working directory). "
|
|
"Note: if you previously set this to `.deer-flow/memory.json`, "
|
|
"the file will now be resolved as `{base_dir}/.deer-flow/memory.json`; "
|
|
"migrate existing data or use an absolute path to preserve the old location."
|
|
),
|
|
)
|
|
storage_class: str = Field(
|
|
default="deerflow.agents.memory.storage.FileMemoryStorage",
|
|
description="The class path for memory storage provider",
|
|
)
|
|
debounce_seconds: int = Field(
|
|
default=30,
|
|
ge=1,
|
|
le=300,
|
|
description="Seconds to wait before processing queued updates (debounce)",
|
|
)
|
|
model_name: str | None = Field(
|
|
default=None,
|
|
description="Model name to use for memory updates (None = use default model)",
|
|
)
|
|
max_facts: int = Field(
|
|
default=100,
|
|
ge=10,
|
|
le=500,
|
|
description="Maximum number of facts to store",
|
|
)
|
|
fact_confidence_threshold: float = Field(
|
|
default=0.7,
|
|
ge=0.0,
|
|
le=1.0,
|
|
description="Minimum confidence threshold for storing facts",
|
|
)
|
|
injection_enabled: bool = Field(
|
|
default=True,
|
|
description="Whether to inject memory into system prompt",
|
|
)
|
|
max_injection_tokens: int = Field(
|
|
default=2000,
|
|
ge=100,
|
|
le=8000,
|
|
description="Maximum tokens to use for memory injection",
|
|
)
|
|
token_counting: Literal["tiktoken", "char"] = Field(
|
|
default="tiktoken",
|
|
description=(
|
|
"Token counting strategy for memory-injection budgeting. "
|
|
"'tiktoken' is accurate but the encoding's BPE data may be "
|
|
"downloaded from a public network endpoint on first use, which "
|
|
"can block for a long time in network-restricted environments "
|
|
"(see issue #3402/#3429). 'char' uses a network-free "
|
|
"CJK-aware character-based estimate and never touches tiktoken."
|
|
),
|
|
)
|
|
guaranteed_categories: list[str] = Field(
|
|
default_factory=lambda: ["correction"],
|
|
description=(
|
|
"Fact categories that are always injected into the prompt regardless "
|
|
"of the regular token budget. These facts are allocated from a "
|
|
"separate reserved budget (``guaranteed_token_budget``). "
|
|
"This ensures high-value facts such as explicit user corrections "
|
|
"are never silently dropped when the token budget is tight."
|
|
),
|
|
)
|
|
guaranteed_token_budget: int = Field(
|
|
default=500,
|
|
ge=50,
|
|
le=2000,
|
|
description=(
|
|
"Token ceiling for guaranteed-category facts. "
|
|
"Guaranteed facts are selected first from this budget and placed at "
|
|
"the front of the Facts block so they cannot be evicted by regular "
|
|
"facts. In the common case the total output still fits within "
|
|
"``max_injection_tokens`` (guaranteed lines displace regular ones); "
|
|
"the budget becomes additive only when guaranteed lines alone push "
|
|
"the output past ``max_injection_tokens``, in which case the "
|
|
"safety-truncation ceiling is raised accordingly."
|
|
),
|
|
)
|
|
|
|
|
|
# Global configuration instance
|
|
_memory_config: MemoryConfig = MemoryConfig()
|
|
|
|
|
|
def get_memory_config() -> MemoryConfig:
|
|
"""Get the current memory configuration."""
|
|
return _memory_config
|
|
|
|
|
|
def set_memory_config(config: MemoryConfig) -> None:
|
|
"""Set the memory configuration."""
|
|
global _memory_config
|
|
_memory_config = config
|
|
|
|
|
|
def load_memory_config_from_dict(config_dict: dict) -> None:
|
|
"""Load memory configuration from a dictionary."""
|
|
global _memory_config
|
|
_memory_config = MemoryConfig(**config_dict)
|