From d300e3597fa9c2faee1862136f9de7028695bb69 Mon Sep 17 00:00:00 2001
From: Daoyuan Li <94409450+DaoyuanLi2816@users.noreply.github.com>
Date: Thu, 9 Jul 2026 23:32:51 -0700
Subject: [PATCH] Correct memory-config documentation to match the code (#3995)

Two memory-config docs disagreed with the actual defaults/behavior in
`config/memory_config.py` and `agents/memory/storage.py`:

- backend/AGENTS.md: `staleness_age_days` was documented as "default: 180;
  range: 1-3650" but the field is `default=90, ge=30, le=365`;
  `staleness_max_removals_per_cycle` was documented as "default: 5; range:
  1-20" but the field is `default=10, ge=1, le=50`.

- config.example.yaml: the `storage_path` comment said "Path relative to
  backend directory", but a relative `storage_path` resolves against the data
  `base_dir` (`get_paths().base_dir / p`), not the backend working directory,
  and an absolute path is what opts out of per-user isolation (matching the
  field's own description in `memory_config.py`).

Doc-only change; no behavior change.
---
 backend/AGENTS.md   | 4 ++--
 config.example.yaml | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/backend/AGENTS.md b/backend/AGENTS.md
index 6bb7885b1..c8b39bd9d 100644
--- a/backend/AGENTS.md
+++ b/backend/AGENTS.md
@@ -594,9 +594,9 @@ Focused regression coverage for the updater lives in `backend/tests/test_memory_
 - `max_injection_tokens` - Token limit for prompt injection (2000)
 - `token_counting` - Token counting strategy for the injection budget: `tiktoken` (default, accurate but may download BPE data from a public endpoint on first use — can block for a long time in network-restricted environments, see issues #3402/#3429) or `char` (network-free CJK-aware char estimate, never touches tiktoken)
 - `staleness_review_enabled` - Enable proactive staleness pruning of aged facts (default: `true`; only triggers when aged candidates exist)
-- `staleness_age_days` - Age in days before a fact becomes a staleness candidate (default: 180; range: 1–3650)
+- `staleness_age_days` - Age in days before a fact becomes a staleness candidate (default: 90; range: 30–365)
 - `staleness_min_candidates` - Minimum aged candidates required to trigger a review cycle (default: 3; range: 1–50)
-- `staleness_max_removals_per_cycle` - Maximum facts removed in a single cycle; lowest-confidence entries are kept when the LLM requests more (default: 5; range: 1–20)
+- `staleness_max_removals_per_cycle` - Maximum facts removed in a single cycle; lowest-confidence entries are kept when the LLM requests more (default: 10; range: 1–50)
 - `staleness_protected_categories` - Fact categories that are never pruned by staleness review (default: `["correction"]`)
 - `consolidation_enabled` - Enable memory consolidation (default: `true`; no extra API call — runs in the same LLM invocation as the normal memory update)
 - `consolidation_min_facts` - Minimum facts in a category to trigger consolidation review (default: 8; range: 3–30)
diff --git a/config.example.yaml b/config.example.yaml
index 3ea98e048..039396104 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -1387,7 +1387,7 @@ summarization:
 # Stores user context and conversation history for personalized responses
 memory:
   enabled: true
-  storage_path: memory.json # Path relative to backend directory
+  storage_path: memory.json # Absolute path opts out of per-user isolation; a relative path resolves under the data base_dir, not the backend directory
   debounce_seconds: 30 # Wait time before processing queued updates
   model_name: null # Use default model
   max_facts: 100 # Maximum number of facts to store