feat(memory): wire StoreRoutingConfig and goal_text into memory recall path (#2484, #2483) (#2520)

* feat(memory): wire StoreRoutingConfig and goal_text into memory recall path (#2484, #2483)

HeuristicRouter, LlmRouter, or HybridRouter based on strategy. Router is
stored as Box<dyn AsyncMemoryRouter> and recall_routed_async() is called
so LLM-based classification actually fires instead of silently degrading
to heuristic. routing_classifier_provider is resolved from provider_pool
at config-apply time using the existing resolve_background_provider pattern.

passes it to remember() and remember_with_parts() enabling goal-conditioned
write gating in A-MAC admission control. All test call sites updated with
None. Zero behavior change when goal_conditioned_write = false.

Breaking: RoutingConfig and RoutingStrategy removed; use StoreRoutingConfig
and [memory.store_routing] instead.

* fix(memory): correct goal_text doc comment in MemoryState

Author: bug-ops

CHANGELOG.md

@@ -23,6 +23,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - metrics: add `sanitizer_injection_fp_local` counter for injection flags on local (`ToolResult`) sources (#2515)
 - metrics: add `pii_ner_timeouts` counter for NER classifier timeout events (#2516)
+- feat(memory): `StoreRoutingConfig` (`[memory.store_routing]`) is now wired into `build_router()` — strategy `heuristic`/`llm`/`hybrid` and `routing_classifier_provider` are resolved at config-apply time; the router is constructed each turn and uses the async `route_async()` path so LLM-based classification actually fires (closes #2484)
+- feat(memory): `goal_text` from raw user input is now propagated to A-MAC admission control — `MemoryState.goal_text` is set at the start of each user turn and passed to `remember()` and `remember_with_parts()` enabling goal-conditioned write gating when `goal_conditioned_write = true` (closes #2483)
+- feat(memory): `AsyncMemoryRouter` trait now implemented for `HeuristicRouter` and `HybridRouter`; `SemanticMemory::recall_routed_async()` added to dispatch routing via the async path; `parse_route_str` is now public
+
+### Removed
+
+- **BREAKING**: `RoutingConfig` and `RoutingStrategy` removed from `zeph-config` — superseded by `StoreRoutingConfig` / `StoreRoutingStrategy`; the `[memory.routing]` TOML section is no longer recognised (use `[memory.store_routing]` instead)
 
 ## [0.18.1] - 2026-03-31
 

crates/zeph-config/src/lib.rs

@@ -55,8 +55,8 @@ pub use logging::{LogRotation, LoggingConfig};
 pub use memory::{
     AdmissionConfig, AdmissionStrategy, AdmissionWeights, BeliefRevisionConfig, CompressionConfig,
     CompressionStrategy, ContextStrategy, DigestConfig, DocumentConfig, GraphConfig, MemoryConfig,
-    NoteLinkingConfig, PruningStrategy, RoutingConfig, RoutingStrategy, RpeConfig, SemanticConfig,
-    SessionsConfig, SidequestConfig, TierConfig, VectorBackend,
+    NoteLinkingConfig, PruningStrategy, RpeConfig, SemanticConfig, SessionsConfig, SidequestConfig,
+    StoreRoutingConfig, StoreRoutingStrategy, TierConfig, VectorBackend,
 };
 pub use providers::{
     BanditConfig, CandleConfig, CandleInlineConfig, CascadeClassifierMode, CascadeConfig,

crates/zeph-config/src/memory.rs

@@ -722,8 +722,6 @@ pub struct MemoryConfig {
     #[serde(default)]
     pub sidequest: SidequestConfig,
     #[serde(default)]
-    pub routing: RoutingConfig,
-    #[serde(default)]
     pub graph: GraphConfig,
     /// Store a lightweight session summary to the vector store on shutdown when no session
     /// summary exists yet for this conversation. Enables cross-session recall for short or
@@ -934,23 +932,6 @@ impl Default for SemanticConfig {
     }
 }
 
-/// Routing strategy for memory backend selection.
-#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, Eq)]
-#[serde(rename_all = "snake_case")]
-pub enum RoutingStrategy {
-    /// Heuristic-based routing using query characteristics.
-    #[default]
-    Heuristic,
-}
-
-/// Configuration for query-aware memory routing (#1162).
-#[derive(Debug, Clone, Default, Deserialize, Serialize)]
-#[serde(default)]
-pub struct RoutingConfig {
-    /// Routing strategy. Currently only `heuristic` is supported.
-    pub strategy: RoutingStrategy,
-}
-
 /// Compression strategy for active context compression (#1161).
 #[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq)]
 #[serde(tag = "strategy", rename_all = "snake_case")]

crates/zeph-config/src/root.rs

@@ -19,8 +19,8 @@ use crate::features::{
 use crate::learning::LearningConfig;
 use crate::logging::LoggingConfig;
 use crate::memory::{
-    CompressionConfig, DocumentConfig, GraphConfig, MemoryConfig, RoutingConfig, SemanticConfig,
-    SessionsConfig, SidequestConfig, TierConfig, VectorBackend,
+    CompressionConfig, DocumentConfig, GraphConfig, MemoryConfig, SemanticConfig, SessionsConfig,
+    SidequestConfig, TierConfig, VectorBackend,
 };
 use crate::providers::{
     LlmConfig, get_default_embedding_model, get_default_response_cache_ttl_secs,
@@ -192,7 +192,6 @@ impl Default for Config {
                 eviction: zeph_memory::EvictionConfig::default(),
                 compression: CompressionConfig::default(),
                 sidequest: SidequestConfig::default(),
-                routing: RoutingConfig::default(),
                 graph: GraphConfig::default(),
                 compression_guidelines: zeph_memory::CompressionGuidelinesConfig::default(),
                 shutdown_summary: true,

crates/zeph-core/src/agent/builder.rs

@@ -14,7 +14,8 @@ use super::session_config::{AgentSessionConfig, CONTEXT_BUDGET_RESERVE_RATIO};
 use crate::agent::state::ProviderConfigSnapshot;
 use crate::channel::Channel;
 use crate::config::{
-    CompressionConfig, LearningConfig, ProviderEntry, RoutingConfig, SecurityConfig, TimeoutConfig,
+    CompressionConfig, LearningConfig, ProviderEntry, SecurityConfig, StoreRoutingConfig,
+    TimeoutConfig,
 };
 use crate::config_watcher::ConfigEvent;
 use crate::context::ContextBudget;
@@ -980,7 +981,7 @@ impl<C: Channel> Agent<C> {
     }
 
     #[must_use]
-    pub fn with_routing(mut self, routing: RoutingConfig) -> Self {
+    pub fn with_routing(mut self, routing: StoreRoutingConfig) -> Self {
         self.context_manager.routing = routing;
         self
     }
@@ -1407,7 +1408,7 @@ mod tests {
         MockChannel, MockToolExecutor, create_test_registry, mock_provider,
     };
     use super::*;
-    use crate::config::{CompressionStrategy, RoutingStrategy};
+    use crate::config::{CompressionStrategy, StoreRoutingConfig, StoreRoutingStrategy};
 
     fn make_agent() -> Agent<MockChannel> {
         Agent::new(
@@ -1448,13 +1449,14 @@ mod tests {
 
     #[test]
     fn with_routing_sets_routing_config() {
-        let routing = RoutingConfig {
-            strategy: RoutingStrategy::Heuristic,
+        let routing = StoreRoutingConfig {
+            strategy: StoreRoutingStrategy::Heuristic,
+            ..StoreRoutingConfig::default()
         };
         let agent = make_agent().with_routing(routing);
         assert_eq!(
             agent.context_manager.routing.strategy,
-            RoutingStrategy::Heuristic,
+            StoreRoutingStrategy::Heuristic,
             "routing strategy must be set by with_routing"
         );
     }
@@ -1474,7 +1476,7 @@ mod tests {
         let agent = make_agent();
         assert_eq!(
             agent.context_manager.routing.strategy,
-            RoutingStrategy::Heuristic,
+            StoreRoutingStrategy::Heuristic,
             "default routing strategy must be Heuristic"
         );
     }

crates/zeph-core/src/agent/context/assembly.rs

@@ -275,7 +275,7 @@ impl<C: Channel> Agent<C> {
         query: &str,
         token_budget: usize,
         tc: &TokenCounter,
-        router: Option<&dyn zeph_memory::MemoryRouter>,
+        router: Option<&dyn zeph_memory::AsyncMemoryRouter>,
     ) -> Result<(Option<Message>, Option<f32>), super::super::error::AgentError> {
         let Some(memory) = &memory_state.memory else {
             return Ok((None, None));
@@ -286,7 +286,7 @@ impl<C: Channel> Agent<C> {
 
         let recalled = if let Some(r) = router {
             memory
-                .recall_routed(query, memory_state.recall_limit, None, r)
+                .recall_routed_async(query, memory_state.recall_limit, None, r)
                 .await?
         } else {
             memory
@@ -891,6 +891,7 @@ impl<C: Channel> Agent<C> {
 
             let tc = self.metrics.token_counter.clone();
             let router = self.context_manager.build_router();
+            let router_ref: &dyn zeph_memory::AsyncMemoryRouter = router.as_ref();
             let memory_state = &self.memory_state;
             let index = &self.index;
 
@@ -914,7 +915,7 @@ impl<C: Channel> Agent<C> {
                     &query,
                     alloc.semantic_recall,
                     &tc,
-                    Some(&router),
+                    Some(router_ref),
                 )
                 .await
                 .map(|(msg, score)| ContextSlot::SemanticRecall(msg, score))

crates/zeph-core/src/agent/context/tests.rs

@@ -3185,6 +3185,7 @@ fn make_mem_state(
         context_strategy: crate::config::ContextStrategy::default(),
         crossover_turn_threshold: 20,
         rpe_router: None,
+        goal_text: None,
     }
 }
 

crates/zeph-core/src/agent/context_manager.rs

@@ -1,7 +1,9 @@
 // SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-use crate::config::{CompressionConfig, RoutingConfig};
+use std::sync::Arc;
+
+use crate::config::{CompressionConfig, StoreRoutingConfig};
 use crate::context::ContextBudget;
 
 /// Lifecycle state of the compaction subsystem within a single session.
@@ -119,8 +121,11 @@ pub(crate) struct ContextManager {
     pub(super) prune_protect_tokens: usize,
     /// Compression configuration for proactive compression (#1161).
     pub(super) compression: CompressionConfig,
-    /// Routing configuration for query-aware memory routing (#1162).
-    pub(super) routing: RoutingConfig,
+    /// Routing configuration for query-aware memory routing (#1162, #2484).
+    pub(super) routing: StoreRoutingConfig,
+    /// Resolved provider for LLM/hybrid routing. `None` when strategy is `Heuristic`
+    /// or when the named provider could not be resolved from the pool.
+    pub(super) store_routing_provider: Option<Arc<zeph_llm::any::AnyProvider>>,
     /// Compaction lifecycle state. Replaces four independent boolean/u8 fields to make
     /// invalid states unrepresentable. See [`CompactionState`] for the full transition map.
     pub(super) compaction: CompactionState,
@@ -144,7 +149,8 @@ impl ContextManager {
             compaction_preserve_tail: 6,
             prune_protect_tokens: 40_000,
             compression: CompressionConfig::default(),
-            routing: RoutingConfig::default(),
+            routing: StoreRoutingConfig::default(),
+            store_routing_provider: None,
             compaction: CompactionState::Ready,
             compaction_cooldown_turns: 2,
             turns_since_last_hard_compaction: None,
@@ -204,11 +210,44 @@ impl ContextManager {
 
     /// Build a memory router from the current routing configuration.
     ///
-    /// The router is stateless and cheap to construct per turn.
-    pub(super) fn build_router(&self) -> zeph_memory::HeuristicRouter {
-        use crate::config::RoutingStrategy;
+    /// Returns a `Box<dyn AsyncMemoryRouter>` so callers can use `route_async()` for LLM-based
+    /// classification. `HeuristicRouter` implements `AsyncMemoryRouter` via a blanket impl that
+    /// delegates to the sync `route_with_confidence`.
+    pub(super) fn build_router(&self) -> Box<dyn zeph_memory::AsyncMemoryRouter + Send + Sync> {
+        use crate::config::StoreRoutingStrategy;
+        if !self.routing.enabled {
+            return Box::new(zeph_memory::HeuristicRouter);
+        }
+        let fallback = zeph_memory::router::parse_route_str(
+            &self.routing.fallback_route,
+            zeph_memory::MemoryRoute::Hybrid,
+        );
         match self.routing.strategy {
-            RoutingStrategy::Heuristic => zeph_memory::HeuristicRouter,
+            StoreRoutingStrategy::Heuristic => Box::new(zeph_memory::HeuristicRouter),
+            StoreRoutingStrategy::Llm => {
+                let Some(provider) = self.store_routing_provider.clone() else {
+                    tracing::warn!(
+                        "store_routing: strategy=llm but no provider resolved; \
+                         falling back to heuristic"
+                    );
+                    return Box::new(zeph_memory::HeuristicRouter);
+                };
+                Box::new(zeph_memory::LlmRouter::new(provider, fallback))
+            }
+            StoreRoutingStrategy::Hybrid => {
+                let Some(provider) = self.store_routing_provider.clone() else {
+                    tracing::warn!(
+                        "store_routing: strategy=hybrid but no provider resolved; \
+                         falling back to heuristic"
+                    );
+                    return Box::new(zeph_memory::HeuristicRouter);
+                };
+                Box::new(zeph_memory::HybridRouter::new(
+                    provider,
+                    fallback,
+                    self.routing.confidence_threshold,
+                ))
+            }
         }
     }
 

crates/zeph-core/src/agent/learning.rs

@@ -1017,7 +1017,10 @@ impl<C: Channel> Agent<C> {
 
     /// Resolve a named provider from the pool, falling back to the primary provider.
     /// Returns a clone of the primary provider if the name is empty, unknown, or resolution fails.
-    fn resolve_background_provider(&self, provider_name: &str) -> zeph_llm::any::AnyProvider {
+    pub(super) fn resolve_background_provider(
+        &self,
+        provider_name: &str,
+    ) -> zeph_llm::any::AnyProvider {
         if provider_name.is_empty() {
             return self.provider.clone();
         }

crates/zeph-core/src/agent/mod.rs

@@ -326,6 +326,7 @@ impl<C: Channel> Agent<C> {
                 context_strategy: crate::config::ContextStrategy::default(),
                 crossover_turn_threshold: 20,
                 rpe_router: None,
+                goal_text: None,
             },
             skill_state: SkillState {
                 registry,
@@ -3813,6 +3814,10 @@ impl<C: Channel> Agent<C> {
             set.extend(urls);
         }
 
+        // Capture raw user input as goal text for A-MAC goal-conditioned write gating (#2483).
+        // Derived from the raw input text before context assembly to avoid timing dependencies.
+        self.memory_state.goal_text = Some(text.clone());
+
         // Image parts intentionally excluded — base64 payloads too large for message history.
         self.persist_message(Role::User, &text, &[], false).await;
         self.push_message(user_msg);
@@ -4848,7 +4853,21 @@ impl<C: Channel> Agent<C> {
         self.context_manager.compaction_cooldown_turns = config.memory.compaction_cooldown_turns;
         self.context_manager.prune_protect_tokens = config.memory.prune_protect_tokens;
         self.context_manager.compression = config.memory.compression.clone();
-        self.context_manager.routing = config.memory.routing.clone();
+        self.context_manager.routing = config.memory.store_routing.clone();
+        // Resolve routing_classifier_provider from the provider pool (#2484).
+        self.context_manager.store_routing_provider = if config
+            .memory
+            .store_routing
+            .routing_classifier_provider
+            .is_empty()
+        {
+            None
+        } else {
+            let resolved = self.resolve_background_provider(
+                &config.memory.store_routing.routing_classifier_provider,
+            );
+            Some(std::sync::Arc::new(resolved))
+        };
         self.memory_state.cross_session_score_threshold =
             config.memory.cross_session_score_threshold;