fix(hindsight): replace destructive aretain_batch with safe file-based retain

[kumaxs]

Summary

Background Review fork was calling hindsight_retain with the parent session_id, causing destructive overwrites of auto-retained session documents in Hindsight. The tool description was misleading — it advertised "Store information" without disclosing that every retain is a full document overwrite (not an incremental append) and that auto_retain already continuously maintains memories in the background.

Changes

1. plugins/memory/hindsight/__init__.py — Safe file-based retain

hindsight_retain tool now uses Hindsight's file retain API instead of direct aretain_batch. Each call generates a unique filename:

{agent}_{channel}_{user}_{session}_{uuid}.md

The UUID guarantees no collision with auto-retained session documents. File retain also enables richer content (markdown formatting, structured text).

2. plugins/memory/hindsight/__init__.py — Accurate tool description

Old: "Store information to long-term memory. Hindsight automatically extracts structured facts, resolves entities, and indexes for retrieval."

New: "This tool grants one dedicated extra memory record. Hindsight's auto_retain continuously maintains memories in the background — do not use this tool for routine memory retention. All long-term essential core information must be stored in memory.md; saving such content through this tool is prohibited under all circumstances."

3. agent/background_review.py — Guided prompt

The _MEMORY_REVIEW_PROMPT now tells the model to:

• Write long-term essential core info to memory.md
• Store important on-demand info to memory provider tools
• Skip if nothing worth saving

Verification

• Dry-run: filename generation verified (all components present, sanitization works)
• Real API test: file retain submitted successfully against live Hindsight instance (operation tracked)
• Syntax: all modified files pass py_compile
• Auto-retain (sync_turn) is completely unaffected — it uses the internal aretain_batch API, not the tool

Closes #55816

[teknium1]

Thanks for investigating the Hindsight overwrite risk.

Automated hermes-sweeper review found that the reported Background Review route is already isolated on current main:

• agent/background_review.py:675-689 creates the review fork with skip_memory=True, explicitly preventing external memory-provider ingestion, recall, and sync side effects.
• plugins/memory/hindsight/__init__.py:1710-1722 does not forward a model-supplied document_id through hindsight_retain; auto-retain supplies its session document identifier separately at :1681-1686.
• This isolation was implemented by 4ece521bcf37401686e73f1d08ebaa87caaae05a (fix(run_agent): isolate background review fork from external memory plugins (#27190)).

Closing as implemented on main.