docs: add human confirmation firewall research report

agent/context_snapshots.py

@@ -1,69 +0,0 @@
-"""First-class context snapshot artifacts for live runtime memory evaluation."""
-
-from __future__ import annotations
-
-import json
-import re
-from pathlib import Path
-from typing import Any
-
-from hermes_constants import get_hermes_home
-
-
-_SAFE_SEGMENT_RE = re.compile(r"[^A-Za-z0-9_.-]+")
-
-
-class ContextSnapshotRecorder:
-    """Write per-call prompt-composition artifacts for a Hermes session."""
-
-    def __init__(self, session_id: str, *, enabled: bool = False, base_dir: str | Path | None = None):
-        self.session_id = session_id or "session"
-        self.enabled = bool(enabled)
-        self.base_dir = Path(base_dir) if base_dir else get_hermes_home() / "reports" / "context_snapshots"
-
-    @property
-    def session_dir(self) -> Path:
-        safe_session = _SAFE_SEGMENT_RE.sub("_", self.session_id).strip("._") or "session"
-        return self.base_dir / safe_session
-
-    def record_call(
-        self,
-        api_call_count: int,
-        *,
-        system_prompt: str,
-        memory_provider_system_prompt: str = "",
-        memory_prefetch_raw: str = "",
-        memory_context_block: str = "",
-        api_user_message: str = "",
-        api_messages: list[dict[str, Any]] | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> Path | None:
-        if not self.enabled:
-            return None
-
-        call_dir = self.session_dir / f"call_{api_call_count:03d}"
-        call_dir.mkdir(parents=True, exist_ok=True)
-
-        self._write_text(call_dir / "system_prompt.txt", system_prompt or "")
-        self._write_text(call_dir / "memory_provider_system_prompt.txt", memory_provider_system_prompt or "")
-        self._write_text(call_dir / "memory_prefetch_raw.txt", memory_prefetch_raw or "")
-        self._write_text(call_dir / "memory_context_block.txt", memory_context_block or "")
-        self._write_text(call_dir / "api_user_message.txt", api_user_message or "")
-        self._write_json(call_dir / "api_messages.json", api_messages or [])
-        self._write_json(
-            call_dir / "metadata.json",
-            {
-                "session_id": self.session_id,
-                "api_call_count": api_call_count,
-                **(metadata or {}),
-            },
-        )
-        return call_dir
-
-    @staticmethod
-    def _write_text(path: Path, content: str) -> None:
-        path.write_text(content, encoding="utf-8")
-
-    @staticmethod
-    def _write_json(path: Path, payload: Any) -> None:
-        path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")

docs/hindsight-local-eval.md

@@ -1,132 +0,0 @@
-# Hindsight local eval homes for live Hermes runtime testing
-
-Issue: #1010
-Parent: #985
-
-This document defines a reproducible, profile-scoped evaluation layout for baseline / MemPalace / Hindsight comparisons without requiring Hindsight Cloud.
-
-## Eval home layout
-
-Use three separate `HERMES_HOME` directories so each run has isolated config, memory, sessions, and artifacts.
-
-```text
-~/.hermes/profiles/atlas-baseline/
-  config.yaml
-  .env
-  MEMORY.md
-  USER.md
-  reports/context_snapshots/
-
-~/.hermes/profiles/atlas-mempalace/
-  config.yaml
-  .env
-  MEMORY.md
-  USER.md
-  reports/context_snapshots/
-  plugins/           # if a local MemPalace plugin is installed for this eval lane
-
-~/.hermes/profiles/atlas-hindsight/
-  config.yaml
-  .env
-  MEMORY.md
-  USER.md
-  hindsight/config.json
-  reports/context_snapshots/
-```
-
-## Hindsight local config
-
-The Hindsight provider already loads config from `$HERMES_HOME/hindsight/config.json` first. For the local eval lane, prefer `local_embedded` so Hermes can bring up a local Hindsight daemon without cloud signup.
-
-Example `~/.hermes/profiles/atlas-hindsight/hindsight/config.json`:
-
-```json
-{
-  "mode": "local_embedded",
-  "memory_mode": "context",
-  "recall_prefetch_method": "recall",
-  "llm_provider": "ollama",
-  "llm_model": "gemma3:12b",
-  "api_url": "http://localhost:8888"
-}
-```
-
-Notes:
-- `local_embedded` avoids any Hindsight Cloud dependency.
-- If `profile` is omitted, Hermes now derives a stable local Hindsight profile name from the active profile identity / `HERMES_HOME` instead of collapsing all local runs into the shared legacy `hermes` profile.
-- `local_external` remains valid if you already run a local Hindsight server yourself.
-
-## Runtime switching procedure
-
-Switch by exporting `HERMES_HOME` before launching Hermes.
-
-### 1. Baseline
-
-```bash
-export HERMES_HOME="$HOME/.hermes/profiles/atlas-baseline"
-unset HERMES_CONTEXT_SNAPSHOTS
-hermes chat
-```
-
-### 2. MemPalace lane
-
-```bash
-export HERMES_HOME="$HOME/.hermes/profiles/atlas-mempalace"
-export HERMES_CONTEXT_SNAPSHOTS=1
-hermes chat
-```
-
-### 3. Hindsight lane
-
-```bash
-export HERMES_HOME="$HOME/.hermes/profiles/atlas-hindsight"
-export HERMES_CONTEXT_SNAPSHOTS=1
-hermes chat
-```
-
-## Raw artifact capture
-
-When `HERMES_CONTEXT_SNAPSHOTS=1` is enabled, Hermes writes first-class prompt-composition artifacts under the active home by default.
-
-Artifact tree:
-
-```text
-$HERMES_HOME/reports/context_snapshots/<session-id>/call_001/
-  system_prompt.txt
-  memory_provider_system_prompt.txt
-  memory_prefetch_raw.txt
-  memory_context_block.txt
-  api_user_message.txt
-  api_messages.json
-  metadata.json
-```
-
-Minimum files a benchmark should inspect:
-- `system_prompt.txt`
-- `memory_prefetch_raw.txt`
-- `memory_context_block.txt`
-- `api_user_message.txt`
-- `api_messages.json`
-
-These prove:
-- what the system prompt was
-- what the provider prefetched
-- what entered `<memory-context>`
-- what the final API user message looked like
-- what full payload reached the model
-
-## Follow-on benchmark workflow
-
-A benchmark issue can now consume this path without redoing integration work:
-1. pick one eval home (`atlas-baseline`, `atlas-mempalace`, `atlas-hindsight`)
-2. export the corresponding `HERMES_HOME`
-3. run Hermes on the same prompt set
-4. compare the snapshot artifacts in `reports/context_snapshots/`
-5. score recall quality and answer quality separately
-
-## Why this is sovereign
-
-- no hosted Hindsight Cloud dependency is required
-- the Hindsight config is profile-scoped under `hindsight/config.json`
-- the runtime artifacts stay under the active `HERMES_HOME`
-- switching between baseline / MemPalace / Hindsight is just a `HERMES_HOME` swap

plugins/memory/hindsight/__init__.py

@@ -178,25 +178,6 @@ def _load_config() -> dict:
     }
 
 
-def _derive_local_profile_name(agent_identity: str = "", hermes_home: str = "") -> str:
-    """Return a stable profile name for local embedded Hindsight storage.
-
-    Prefer the active Hermes profile identity when available, otherwise fall back
-    to the basename of the active HERMES_HOME path. This prevents all local
-    Hindsight eval homes from sharing the legacy default profile name "hermes".
-    """
-    from pathlib import Path
-    import re
-
-    raw = (agent_identity or "").strip()
-    if not raw and hermes_home:
-        raw = Path(hermes_home).name.strip()
-    if not raw:
-        raw = "hermes"
-    safe = re.sub(r"[^A-Za-z0-9_.-]+", "-", raw).strip(".-_")
-    return safe or "hermes"
-
-
 # ---------------------------------------------------------------------------
 # MemoryProvider implementation
 # ---------------------------------------------------------------------------
@@ -487,8 +468,6 @@ class HindsightMemoryProvider(MemoryProvider):
 
     def initialize(self, session_id: str, **kwargs) -> None:
         self._session_id = session_id
-        hermes_home = str(kwargs.get("hermes_home") or "")
-        agent_identity = str(kwargs.get("agent_identity") or "")
 
         # Check client version and auto-upgrade if needed
         try:
@@ -521,11 +500,6 @@ class HindsightMemoryProvider(MemoryProvider):
         # "local" is a legacy alias for "local_embedded"
         if self._mode == "local":
             self._mode = "local_embedded"
-        if self._mode == "local_embedded" and not self._config.get("profile"):
-            self._config["profile"] = _derive_local_profile_name(
-                agent_identity=agent_identity,
-                hermes_home=hermes_home,
-            )
         self._api_key = self._config.get("apiKey") or self._config.get("api_key") or os.environ.get("HINDSIGHT_API_KEY", "")
         default_url = _DEFAULT_LOCAL_URL if self._mode in ("local_embedded", "local_external") else _DEFAULT_API_URL
         self._api_url = self._config.get("api_url") or os.environ.get("HINDSIGHT_API_URL", default_url)

research_human_confirmation_firewall.md

@@ -0,0 +1,515 @@
+# Human Confirmation Firewall: Research Report
+## Implementation Patterns for Hermes Agent
+
+**Issue:** #878  
+**Parent:** #659  
+**Priority:** P0  
+**Scope:** Human-in-the-loop safety patterns for tool calls, crisis handling, and irreversible actions
+
+---
+
+## Executive Summary
+
+Hermes already has a partial human confirmation firewall, but it is narrow.
+
+Current repo state shows:
+- a real **pre-execution gate** for dangerous terminal commands in `tools/approval.py`
+- a partial **confidence-threshold path** via `_smart_approve()` in `tools/approval.py`
+- gateway support for blocking approval resolution in `gateway/run.py`
+
+What is still missing is the core recommendation from this research issue:
+- **confidence scoring on all tool calls**, not just terminal commands that already matched a dangerous regex
+- a **hard pre-execution human gate for crisis interventions**, especially any action that would auto-respond to suicidal content
+- a consistent way to classify actions into:
+  1. pre-execution gate
+  2. post-execution review
+  3. confidence-threshold execution
+
+Recommendation:
+- use **Pattern 1: Pre-Execution Gate** for crisis interventions and irreversible/high-impact actions
+- use **Pattern 3: Confidence Threshold** for normal operations
+- reserve **Pattern 2: Post-Execution Review** only for low-risk and reversible actions
+
+The next implementation step should be a **tool-call risk assessment layer** that runs before dispatch in `model_tools.handle_function_call()`, assigns a score and pattern to every tool call, and routes only the highest-risk calls into mandatory human confirmation.
+
+---
+
+## 1. The Three Proven Patterns
+
+### Pattern 1: Pre-Execution Gate
+
+Definition:
+- halt before execution
+- show the proposed action to the human
+- require explicit approval or denial
+
+Best for:
+- destructive actions
+- irreversible side effects
+- crisis interventions
+- actions that affect another human's safety, money, infrastructure, or private data
+
+Strengths:
+- strongest safety guarantee
+- simplest audit story
+- prevents the most catastrophic failure mode: acting first and apologizing later
+
+Weaknesses:
+- adds latency
+- creates operator burden if overused
+- should not be applied to every ordinary tool call
+
+### Pattern 2: Post-Execution Review
+
+Definition:
+- execute first
+- expose result to human
+- allow rollback or follow-up correction
+
+Best for:
+- reversible operations
+- low-risk actions with fast recovery
+- tasks where human review matters but immediate execution is acceptable
+
+Strengths:
+- low friction
+- fast iteration
+- useful when rollback is practical
+
+Weaknesses:
+- unsafe for crisis or destructive actions
+- only works when rollback actually exists
+- a poor fit for external communication or life-safety contexts
+
+### Pattern 3: Confidence Threshold
+
+Definition:
+- compute a risk/confidence score before execution
+- auto-execute high-confidence safe actions
+- request confirmation for lower-confidence or higher-risk actions
+
+Best for:
+- mixed-risk tool ecosystems
+- day-to-day operations where always-confirm would be too expensive
+- systems with a large volume of ordinary, safe reads and edits
+
+Strengths:
+- best balance of speed and safety
+- scales across many tool types
+- allows targeted human attention where it matters most
+
+Weaknesses:
+- depends on a good scoring model
+- weak scoring creates false negatives or unnecessary prompts
+- must remain inspectable and debuggable
+
+---
+
+## 2. What Hermes Already Has
+
+## 2.1 Existing Pre-Execution Gate for Dangerous Terminal Commands
+
+`tools/approval.py` already implements a real pre-execution confirmation path for dangerous shell commands.
+
+Observed components:
+- `DANGEROUS_PATTERNS`
+- `detect_dangerous_command()`
+- `prompt_dangerous_approval()`
+- `check_dangerous_command()`
+- gateway queueing and resolution support in the same module
+
+This is already Pattern 1.
+
+Current behavior:
+- dangerous terminal commands are detected before execution
+- the user can allow once / session / always / deny
+- gateway sessions can block until approval resolves
+
+This is a strong foundation, but it is limited to a subset of terminal commands.
+
+## 2.2 Partial Confidence Threshold via Smart Approvals
+
+Hermes also already has a partial Pattern 3.
+
+Observed component:
+- `_smart_approve()` in `tools/approval.py`
+
+Current behavior:
+- only runs **after** a command has already been flagged by dangerous-pattern detection
+- uses the auxiliary LLM to decide:
+  - approve
+  - deny
+  - escalate
+
+This means Hermes has a confidence-threshold mechanism, but only for **already-flagged dangerous terminal commands**.
+
+What it does not yet do:
+- score all tool calls
+- classify non-terminal tools
+- distinguish crisis interventions from normal ops
+- produce a shared risk model across the tool surface
+
+## 2.3 Blocking Approval UX in Gateway
+
+`gateway/run.py` already routes `/approve` and `/deny` into the blocking approval path.
+
+This means the infrastructure for a true human confirmation firewall already exists in messaging contexts.
+
+That is important because the missing work is not "invent human approval from zero."
+The missing work is:
+- expand the scope from dangerous shell commands to **all tool calls that matter**
+- make the routing policy explicit and inspectable
+
+---
+
+## 3. What Hermes Still Lacks
+
+## 3.1 No Universal Tool-Call Risk Assessment
+
+The current approval system is command-pattern-centric.
+It is not yet a tool-call firewall.
+
+Missing capability:
+- before dispatch, every tool call should receive a structured assessment:
+  - tool name
+  - side-effect class
+  - reversibility
+  - human-impact potential
+  - crisis relevance
+  - confidence score
+  - recommended confirmation pattern
+
+Natural insertion point:
+- `model_tools.handle_function_call()`
+
+That function already sits at the central dispatch boundary.
+It is the right place to add a pre-dispatch classifier.
+
+## 3.2 No Hard Crisis Gate for Outbound Intervention
+
+Issue #878 explicitly recommends:
+- Pattern 1 for crisis interventions
+- never auto-respond to suicidal content
+
+That recommendation is not yet codified as a global firewall rule.
+
+Missing rule:
+- if a tool call would directly intervene in a crisis context or send outward guidance in response to suicidal content, it must require explicit human confirmation before execution
+
+Examples that should hard-gate:
+- outbound `send_message` content aimed at a suicidal user
+- any future tool that places calls, escalates emergencies, or contacts third parties about a crisis
+- any autonomous action that claims a person should or should not take a life-safety step
+
+## 3.3 No First-Class Post-Execution Review Policy
+
+Hermes has approval and denial, but it does not yet have a formal policy for when Pattern 2 is acceptable.
+
+Without a policy, post-execution review tends to get used implicitly rather than intentionally.
+
+That is risky.
+
+Hermes should define Pattern 2 narrowly:
+- only for actions that are both low-risk and reversible
+- only when the system can show the human exactly what happened
+- never for crisis, finance, destructive config, or sensitive comms
+
+---
+
+## 4. Recommended Architecture for Hermes
+
+## 4.1 Add a Tool-Call Assessment Layer
+
+Add a pre-dispatch assessment object for every tool call.
+
+Suggested shape:
+
+```python
+@dataclass
+class ToolCallAssessment:
+    tool_name: str
+    risk_score: float          # 0.0 to 1.0
+    confidence: float          # confidence in the assessment itself
+    pattern: str               # pre_execution_gate | post_execution_review | confidence_threshold
+    requires_human: bool
+    reasons: list[str]
+    reversible: bool
+    crisis_sensitive: bool
+```
+
+Suggested execution point:
+- inside `model_tools.handle_function_call()` before `orchestrator.dispatch()`
+
+Why here:
+- one place covers all tools
+- one place can emit traces
+- one place can remain model-agnostic
+- one place lets plugins observe or override the assessment
+
+## 4.2 Classify Tool Calls by Side-Effect Class
+
+Suggested first-pass taxonomy:
+
+### A. Read-only
+Examples:
+- `read_file`
+- `search_files`
+- `browser_snapshot`
+- `browser_console` read-only inspection
+
+Pattern:
+- confidence threshold
+- almost always auto-execute
+- human confirmation normally unnecessary
+
+### B. Local reversible edits
+Examples:
+- `patch`
+- `write_file`
+- `todo`
+
+Pattern:
+- confidence threshold
+- human confirmation only when risk score rises because of path sensitivity or scope breadth
+
+### C. External side effects
+Examples:
+- `send_message`
+- `cronjob`
+- `delegate_task`
+- smart-home actuation tools
+
+Pattern:
+- confidence threshold by default
+- pre-execution gate when score exceeds threshold or when context is sensitive
+
+### D. Critical / destructive / crisis-sensitive
+Examples:
+- dangerous `terminal`
+- financial actions
+- deletion / kill / restart / deployment in sensitive paths
+- outbound crisis intervention
+
+Pattern:
+- pre-execution gate
+- never auto-execute on confidence alone
+
+## 4.3 Crisis Override Rule
+
+Add a hard override:
+
+```text
+If tool call is crisis-sensitive AND outbound or irreversible:
+    requires_human = True
+    pattern = pre_execution_gate
+```
+
+This is the most important rule in the issue.
+
+The model may draft the message.
+The human must confirm before the system sends it.
+
+## 4.4 Use Confidence Threshold for Normal Ops
+
+For non-crisis operations, use Pattern 3.
+
+Suggested logic:
+- low risk + high assessment confidence -> auto-execute
+- medium risk or medium confidence -> ask human
+- high risk -> always ask human
+
+Key point:
+- confidence is not just "how sure the LLM is"
+- confidence should combine:
+  - tool type certainty
+  - argument clarity
+  - path sensitivity
+  - external side effects
+  - crisis indicators
+
+---
+
+## 5. Recommended Initial Scoring Factors
+
+A simple initial scorer is enough.
+It does not need to be fancy.
+
+Suggested factors:
+
+### 5.1 Tool class risk
+- read-only tools: very low base risk
+- local mutation tools: moderate base risk
+- external communication / automation tools: higher base risk
+- shell execution: variable, often high
+
+### 5.2 Target sensitivity
+Examples:
+- `/tmp` or local scratch paths -> lower
+- repo files under git -> medium
+- system config, credentials, secrets, gateway lifecycle -> high
+- human-facing channels -> high if message content is sensitive
+
+### 5.3 Reversibility
+- reversible -> lower
+- difficult but possible to undo -> medium
+- practically irreversible -> high
+
+### 5.4 Human-impact content
+- no direct human impact -> low
+- administrative impact -> medium
+- crisis / safety / emotional intervention -> critical
+
+### 5.5 Context certainty
+- arguments are explicit and narrow -> higher confidence
+- arguments are vague, inferred, or broad -> lower confidence
+
+---
+
+## 6. Implementation Plan
+
+## Phase 1: Assessment Without Behavior Change
+
+Goal:
+- score all tool calls
+- log assessment decisions
+- emit traces for review
+- do not yet block new tool categories
+
+Files to touch:
+- `tools/approval.py`
+- `model_tools.py`
+- tests for assessment coverage
+
+Output:
+- risk/confidence trace for every tool call
+- pattern recommendation for every tool call
+
+Why first:
+- lets us calibrate before changing runtime behavior
+- avoids breaking existing workflows blindly
+
+## Phase 2: Hard-Gate Crisis-Sensitive Outbound Actions
+
+Goal:
+- enforce Pattern 1 for crisis interventions
+
+Likely surfaces:
+- `send_message`
+- any future telephony / call / escalation tools
+- other tools with direct human intervention side effects
+
+Rule:
+- never auto-send crisis intervention content without human confirmation
+
+## Phase 3: General Confidence Threshold for Normal Ops
+
+Goal:
+- apply Pattern 3 to all tool calls
+- auto-run clearly safe actions
+- escalate ambiguous or medium-risk actions
+
+Likely thresholds:
+- score < 0.25 -> auto
+- 0.25 to 0.60 -> confirm if confidence is weak
+- > 0.60 -> confirm
+- crisis-sensitive -> always confirm
+
+## Phase 4: Optional Post-Execution Review Lane
+
+Goal:
+- allow Pattern 2 only for explicitly reversible operations
+
+Examples:
+- maybe low-risk messaging drafts saved locally
+- maybe reversible UI actions in specific environments
+
+Important:
+- this phase is optional
+- Hermes should not rely on Pattern 2 for safety-critical flows
+
+---
+
+## 7. Verification Criteria for the Future Implementation
+
+The eventual implementation should prove all of the following:
+
+1. every tool call receives a scored assessment before dispatch
+2. crisis-sensitive outbound actions always require human confirmation
+3. dangerous terminal commands still preserve their current pre-execution gate
+4. clearly safe read-only tool calls are not slowed by unnecessary prompts
+5. assessment traces can be inspected after a run
+6. approval decisions remain session-safe across CLI and gateway contexts
+
+---
+
+## 8. Concrete Recommendations
+
+### Recommendation 1
+Do **not** replace the current dangerous-command approval path.
+Generalize above it.
+
+Why:
+- existing terminal Pattern 1 already works
+- this is the strongest piece of the current firewall
+
+### Recommendation 2
+Add a universal scorer in `model_tools.handle_function_call()`.
+
+Why:
+- that is the first point where Hermes knows the tool name and structured arguments
+- it is the cleanest place to classify all tool calls uniformly
+
+### Recommendation 3
+Treat crisis-sensitive outbound intervention as a separate safety class.
+
+Why:
+- issue #878 explicitly calls for Pattern 1 here
+- this matches Timmy's SOUL-level safety requirements
+
+### Recommendation 4
+Ship scoring traces before enforcement expansion.
+
+Why:
+- you cannot tune thresholds you cannot inspect
+- false positives will otherwise frustrate normal usage
+
+### Recommendation 5
+Use Pattern 3 as the default policy for normal operations.
+
+Why:
+- full manual confirmation on every tool call is too expensive
+- full autonomy is too risky
+- Pattern 3 is the practical middle ground
+
+---
+
+## 9. Bottom Line
+
+Hermes should implement a **two-track human confirmation firewall**:
+
+1. **Pattern 1: Pre-Execution Gate**
+   - crisis interventions
+   - destructive terminal actions
+   - irreversible or safety-critical tool calls
+
+2. **Pattern 3: Confidence Threshold**
+   - all ordinary tool calls
+   - driven by a universal tool-call assessment layer
+   - integrated at the central dispatch boundary
+
+Pattern 2 should remain optional and narrow.
+It is not the primary answer for Hermes.
+
+The repo already contains the beginnings of this system.
+The next step is not new theory.
+It is to turn the existing approval path into a true **tool-call-wide human confirmation firewall**.
+
+---
+
+## References
+
+- Issue #878 — Human Confirmation Firewall Implementation Patterns
+- Issue #659 — Critical Research Tasks
+- `tools/approval.py` — current dangerous-command approval flow and smart approvals
+- `model_tools.py` — central tool dispatch boundary
+- `gateway/run.py` — blocking approval handling for messaging sessions

run_agent.py

@@ -604,8 +604,6 @@ class AIAgent:
         checkpoint_max_snapshots: int = 50,
         pass_session_id: bool = False,
         persist_session: bool = True,
-        context_snapshots_enabled: bool | None = None,
-        context_snapshots_dir: str | None = None,
     ):
         """
         Initialize the AI Agent.
@@ -1131,43 +1129,6 @@ class AIAgent:
         except Exception:
             _agent_cfg = {}
 
-        def _is_enabled(value):
-            if isinstance(value, bool):
-                return value
-            return str(value).strip().lower() in {"1", "true", "yes", "on"}
-
-        _debug_cfg = _agent_cfg.get("debug", {}) if isinstance(_agent_cfg, dict) else {}
-        if not isinstance(_debug_cfg, dict):
-            _debug_cfg = {}
-        _snapshot_cfg = _debug_cfg.get("context_snapshots", {})
-        if not isinstance(_snapshot_cfg, dict):
-            _snapshot_cfg = {}
-        _snapshots_env = os.getenv("HERMES_CONTEXT_SNAPSHOTS")
-        _snapshots_dir_env = os.getenv("HERMES_CONTEXT_SNAPSHOTS_DIR")
-        if context_snapshots_enabled is None:
-            if _snapshots_env is not None:
-                self._context_snapshots_enabled = _is_enabled(_snapshots_env)
-            else:
-                self._context_snapshots_enabled = _is_enabled(_snapshot_cfg.get("enabled", False))
-        else:
-            self._context_snapshots_enabled = bool(context_snapshots_enabled)
-        self._context_snapshots_dir = (
-            context_snapshots_dir
-            or _snapshots_dir_env
-            or _snapshot_cfg.get("dir")
-            or None
-        )
-        try:
-            from agent.context_snapshots import ContextSnapshotRecorder
-            self._context_snapshot_recorder = ContextSnapshotRecorder(
-                session_id=self.session_id,
-                enabled=self._context_snapshots_enabled,
-                base_dir=self._context_snapshots_dir,
-            )
-        except Exception as _snapshot_err:
-            logger.debug("Context snapshot recorder init failed: %s", _snapshot_err)
-            self._context_snapshot_recorder = None
-
         # Persistent memory (MEMORY.md + USER.md) -- loaded from disk
         self._memory_store = None
         self._memory_enabled = False
@@ -8183,17 +8144,12 @@ class AIAgent:
         # Use original_user_message (clean input) — user_message may contain
         # injected skill content that bloats / breaks provider queries.
         _ext_prefetch_cache = ""
-        _memory_provider_prompt_cache = ""
         if self._memory_manager:
             try:
                 _query = original_user_message if isinstance(original_user_message, str) else ""
                 _ext_prefetch_cache = self._memory_manager.prefetch_all(_query) or ""
             except Exception:
                 pass
-            try:
-                _memory_provider_prompt_cache = self._memory_manager.build_system_prompt() or ""
-            except Exception:
-                pass
 
         while (api_call_count < self.max_iterations and self.iteration_budget.remaining > 0) or self._budget_grace_call:
             # Reset per-turn checkpoint dedup so each iteration can take one snapshot
@@ -8261,8 +8217,6 @@ class AIAgent:
             # However, providers like Moonshot AI require a separate 'reasoning_content' field
             # on assistant messages with tool_calls. We handle both cases here.
             api_messages = []
-            _current_api_user_message = ""
-            _current_memory_context_block = ""
             for idx, msg in enumerate(messages):
                 api_msg = msg.copy()
 
@@ -8277,15 +8231,12 @@ class AIAgent:
                         _fenced = build_memory_context_block(_ext_prefetch_cache)
                         if _fenced:
                             _injections.append(_fenced)
-                            _current_memory_context_block = _fenced
                     if _plugin_user_context:
                         _injections.append(_plugin_user_context)
                     if _injections:
                         _base = api_msg.get("content", "")
                         if isinstance(_base, str):
                             api_msg["content"] = _base + "\n\n" + "\n\n".join(_injections)
-                    if isinstance(api_msg.get("content"), str):
-                        _current_api_user_message = api_msg["content"]
 
                 # For ALL assistant messages, pass reasoning back to the API
                 # This ensures multi-turn reasoning context is preserved
@@ -8320,13 +8271,7 @@ class AIAgent:
                 from agent.privacy_filter import PrivacyFilter
                 pf = PrivacyFilter()
                 # Sanitize messages before they reach the provider
-                _pf_result = pf.sanitize_messages(api_messages)
-                if isinstance(_pf_result, tuple):
-                    api_messages, _pf_report = _pf_result
-                    if getattr(pf, "last_report", None) is None:
-                        pf.last_report = _pf_report
-                else:
-                    api_messages = _pf_result
+                api_messages = pf.sanitize_messages(api_messages)
                 if pf.last_report and pf.last_report.had_redactions:
                     logger.info(f"Privacy Filter: Redacted sensitive data from turn payload. Details: {pf.last_report.summary()}")
             except Exception as e:
@@ -8397,27 +8342,6 @@ class AIAgent:
                     new_tcs.append(tc)
                 am["tool_calls"] = new_tcs
 
-            if self._context_snapshot_recorder:
-                try:
-                    self._context_snapshot_recorder.record_call(
-                        api_call_count,
-                        system_prompt=effective_system,
-                        memory_provider_system_prompt=_memory_provider_prompt_cache,
-                        memory_prefetch_raw=_ext_prefetch_cache,
-                        memory_context_block=_current_memory_context_block,
-                        api_user_message=_current_api_user_message,
-                        api_messages=api_messages,
-                        metadata={
-                            "model": self.model,
-                            "provider": self.provider,
-                            "platform": self.platform or "",
-                            "api_mode": self.api_mode,
-                            "memory_providers": [p.name for p in getattr(self._memory_manager, "providers", [])],
-                        },
-                    )
-                except Exception as _snapshot_err:
-                    logger.debug("Context snapshot capture failed: %s", _snapshot_err)
-
             # Calculate approximate request size for logging
             total_chars = sum(len(str(msg)) for msg in api_messages)
             approx_tokens = estimate_messages_tokens_rough(api_messages)

tests/agent/test_context_snapshots.py

@@ -1,43 +0,0 @@
-from pathlib import Path
-
-from agent.context_snapshots import ContextSnapshotRecorder
-
-
-def test_disabled_recorder_writes_nothing(tmp_path):
-    recorder = ContextSnapshotRecorder(session_id="session-1", enabled=False, base_dir=tmp_path)
-
-    out = recorder.record_call(
-        1,
-        system_prompt="system",
-        api_messages=[{"role": "user", "content": "hello"}],
-    )
-
-    assert out is None
-    assert not (tmp_path / "session-1").exists()
-
-
-def test_enabled_recorder_writes_expected_artifacts(tmp_path):
-    recorder = ContextSnapshotRecorder(session_id="session-1", enabled=True, base_dir=tmp_path)
-
-    out = recorder.record_call(
-        1,
-        system_prompt="system prompt",
-        memory_provider_system_prompt="# Hindsight Memory\nActive.",
-        memory_prefetch_raw="- remembered fact",
-        memory_context_block="<memory-context>\nremembered\n</memory-context>",
-        api_user_message="What do I prefer?\n\n<memory-context>\nremembered\n</memory-context>",
-        api_messages=[
-            {"role": "system", "content": "system prompt"},
-            {"role": "user", "content": "What do I prefer?"},
-        ],
-        metadata={"provider": "openai", "memory_providers": ["builtin", "hindsight"]},
-    )
-
-    assert out == tmp_path / "session-1" / "call_001"
-    assert (out / "system_prompt.txt").read_text(encoding="utf-8") == "system prompt"
-    assert (out / "memory_provider_system_prompt.txt").read_text(encoding="utf-8").startswith("# Hindsight Memory")
-    assert (out / "memory_prefetch_raw.txt").read_text(encoding="utf-8") == "- remembered fact"
-    assert "<memory-context>" in (out / "memory_context_block.txt").read_text(encoding="utf-8")
-    assert "What do I prefer?" in (out / "api_user_message.txt").read_text(encoding="utf-8")
-    assert (out / "api_messages.json").read_text(encoding="utf-8").startswith("[")
-    assert '"hindsight"' in (out / "metadata.json").read_text(encoding="utf-8")

tests/plugins/memory/test_hindsight_provider.py

@@ -596,26 +596,3 @@ class TestAvailability:
         monkeypatch.setenv("HINDSIGHT_MODE", "local")
         p = HindsightMemoryProvider()
         assert p.is_available()
-
-    def test_local_embedded_profile_defaults_to_agent_identity(self, tmp_path, monkeypatch):
-        config_path = tmp_path / "hindsight" / "config.json"
-        config_path.parent.mkdir(parents=True, exist_ok=True)
-        config_path.write_text(json.dumps({
-            "mode": "local_embedded",
-            "llm_provider": "ollama",
-            "llm_model": "gemma3:12b",
-        }))
-        monkeypatch.setattr(
-            "plugins.memory.hindsight.get_hermes_home",
-            lambda: tmp_path,
-        )
-
-        p = HindsightMemoryProvider()
-        p.initialize(
-            session_id="test-session",
-            hermes_home=str(tmp_path / "profiles" / "atlas-hindsight"),
-            platform="cli",
-            agent_identity="atlas-hindsight",
-        )
-
-        assert p._config["profile"] == "atlas-hindsight"

tests/run_agent/test_run_agent_context_snapshots.py

@@ -1,94 +0,0 @@
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import MagicMock, patch
-import importlib
-import sys
-import types
-
-
-
-def _make_tool_defs(*names: str) -> list:
-    return [
-        {
-            "type": "function",
-            "function": {
-                "name": n,
-                "description": f"{n} tool",
-                "parameters": {"type": "object", "properties": {}},
-            },
-        }
-        for n in names
-    ]
-
-
-
-def _mock_response(content="Done", finish_reason="stop"):
-    msg = SimpleNamespace(content=content, tool_calls=None)
-    choice = SimpleNamespace(message=msg, finish_reason=finish_reason)
-    return SimpleNamespace(choices=[choice], usage=SimpleNamespace(prompt_tokens=1, completion_tokens=1, total_tokens=2))
-
-
-
-def _load_ai_agent():
-    sys.modules.setdefault("agent.auxiliary_client", types.SimpleNamespace(call_llm=lambda *a, **k: ""))
-    run_agent = importlib.import_module("run_agent")
-    return run_agent.AIAgent
-
-
-
-def test_run_conversation_writes_context_snapshot_artifacts(tmp_path):
-    AIAgent = _load_ai_agent()
-
-    class _FakePrivacyFilter:
-        def __init__(self):
-            self.last_report = None
-
-        def sanitize_messages(self, messages):
-            return list(messages)
-
-    with (
-        patch("run_agent.get_tool_definitions", return_value=_make_tool_defs("web_search")),
-        patch("run_agent.check_toolset_requirements", return_value={}),
-        patch("run_agent.OpenAI"),
-        patch("hermes_cli.plugins.invoke_hook", return_value=[]),
-        patch.dict(sys.modules, {"agent.privacy_filter": types.SimpleNamespace(PrivacyFilter=_FakePrivacyFilter)}),
-    ):
-        agent = AIAgent(
-            api_key="test-key-1234567890",
-            base_url="https://example.com/v1",
-            quiet_mode=True,
-            skip_context_files=True,
-            skip_memory=True,
-            context_snapshots_enabled=True,
-            context_snapshots_dir=str(tmp_path),
-        )
-
-    agent.client = MagicMock()
-    agent.client.chat.completions.create.return_value = _mock_response(content="Done")
-    agent._build_system_prompt = MagicMock(return_value="Core system prompt")
-    agent._memory_manager = MagicMock()
-    agent._memory_manager.prefetch_all.return_value = "- remembered preference"
-    agent._memory_manager.build_system_prompt.return_value = "# Hindsight Memory\nActive."
-    agent._memory_manager.providers = [
-        SimpleNamespace(name="builtin"),
-        SimpleNamespace(name="hindsight"),
-    ]
-
-    result = agent.run_conversation("What do I prefer?")
-
-    assert result["final_response"] == "Done"
-
-    call_dir = tmp_path / agent.session_id / "call_001"
-    assert call_dir.exists()
-    assert (call_dir / "system_prompt.txt").read_text(encoding="utf-8") == "Core system prompt"
-    assert (call_dir / "memory_provider_system_prompt.txt").read_text(encoding="utf-8").startswith("# Hindsight Memory")
-    assert (call_dir / "memory_prefetch_raw.txt").read_text(encoding="utf-8") == "- remembered preference"
-    assert "<memory-context>" in (call_dir / "memory_context_block.txt").read_text(encoding="utf-8")
-    api_user_message = (call_dir / "api_user_message.txt").read_text(encoding="utf-8")
-    assert "What do I prefer?" in api_user_message
-    assert "remembered preference" in api_user_message
-    api_messages = (call_dir / "api_messages.json").read_text(encoding="utf-8")
-    assert '"role": "system"' in api_messages
-    assert '"role": "user"' in api_messages
-    metadata = (call_dir / "metadata.json").read_text(encoding="utf-8")
-    assert '"hindsight"' in metadata

tests/test_hindsight_local_eval_doc.py

@@ -1,22 +0,0 @@
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[1]
-DOC = ROOT / "docs" / "hindsight-local-eval.md"
-
-
-def test_hindsight_local_eval_doc_exists_and_covers_switching():
-    assert DOC.exists(), "missing Hindsight local eval doc"
-    text = DOC.read_text(encoding="utf-8")
-    for snippet in (
-        "atlas-baseline",
-        "atlas-mempalace",
-        "atlas-hindsight",
-        "HERMES_HOME",
-        "HERMES_CONTEXT_SNAPSHOTS",
-        "memory_prefetch_raw.txt",
-        "api_user_message.txt",
-        "local_embedded",
-        "hindsight/config.json",
-    ):
-        assert snippet in text