feat(memory): project LLM learning signals

Author: claude

core/src/agent/memory_extraction_runtime.rs

@@ -22,6 +22,11 @@ Each memory must be standalone, concise, scoped, and justified. Return an empty
 const MAX_MEMORY_CONTENT_CHARS: usize = 1_200;
 const MAX_MEMORY_REASON_CHARS: usize = 320;
 const MAX_MEMORY_TAGS: usize = 8;
+const MAX_EVOLUTION_PATTERN_CHARS: usize = 96;
+const MAX_EVOLUTION_TITLE_CHARS: usize = 96;
+const MAX_EVOLUTION_SUMMARY_CHARS: usize = 360;
+const MAX_EVOLUTION_INSTRUCTIONS: usize = 8;
+const MAX_EVOLUTION_INSTRUCTION_CHARS: usize = 320;
 const MAX_RELATED_MEMORY_ITEMS: usize = 5;
 const MAX_RELATED_MEMORY_CHARS: usize = 2_000;
 const MAX_RELATED_MEMORY_CONTENT_CHARS: usize = 320;
@@ -53,6 +58,31 @@ struct ExtractedMemory {
     supersedes: Vec<String>,
     #[serde(default, alias = "conflictsWith", alias = "conflicts")]
     conflicts_with: Vec<String>,
+    #[serde(default)]
+    evolution: Option<ExtractedEvolution>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ExtractedEvolution {
+    #[serde(default)]
+    kind: String,
+    #[serde(default, alias = "patternKey")]
+    pattern_key: String,
+    #[serde(default)]
+    title: String,
+    #[serde(default)]
+    summary: String,
+    #[serde(default, alias = "guidance")]
+    instructions: Vec<String>,
+}
+
+#[derive(Debug)]
+struct EvolutionSignal {
+    kind: &'static str,
+    pattern_key: String,
+    title: String,
+    summary: String,
+    instructions: Vec<String>,
 }
 
 #[derive(Debug, Clone)]
@@ -296,6 +326,7 @@ impl ExtractedMemory {
         }
         let supersedes = normalize_supersedes(self.supersedes, allowed_supersedes);
         let conflicts_with = normalize_related_ids(self.conflicts_with, allowed_supersedes);
+        let evolution = self.evolution.and_then(|signal| signal.normalize(&source));
         let mut item = MemoryItem::new(content)
             .with_type(memory_type)
             .with_importance(importance)
@@ -319,6 +350,21 @@ impl ExtractedMemory {
                 .with_tag("conflict")
                 .with_metadata("conflicts_with", conflicts_with.join(","));
         }
+        if let Some(signal) = evolution {
+            item = item
+                .with_tag("evolution")
+                .with_tag(format!("evolution-{}", signal.kind))
+                .with_metadata("evolution_schema", "a3s.evolution.signal.v1")
+                .with_metadata("evolution_kind", signal.kind)
+                .with_metadata("evolution_pattern", signal.pattern_key)
+                .with_metadata("evolution_title", signal.title)
+                .with_metadata("evolution_summary", signal.summary)
+                .with_metadata(
+                    "evolution_instructions",
+                    serde_json::to_string(&signal.instructions)
+                        .unwrap_or_else(|_| "[]".to_string()),
+                );
+        }
 
         for tag in self
             .tags
@@ -335,6 +381,75 @@ impl ExtractedMemory {
     }
 }
 
+impl ExtractedEvolution {
+    fn normalize(self, source: &str) -> Option<EvolutionSignal> {
+        let kind = match self.kind.trim().to_ascii_lowercase().as_str() {
+            "preference" if matches!(source, "preference" | "decision") => "preference",
+            "skill" if matches!(source, "workflow" | "failure" | "decision") => "skill",
+            "okf" | "knowledge" if matches!(source, "project_fact" | "workflow" | "decision") => {
+                "okf"
+            }
+            _ => return None,
+        };
+        let pattern_key = normalize_evolution_pattern(&self.pattern_key)?;
+        let title = compact(self.title.trim(), MAX_EVOLUTION_TITLE_CHARS);
+        let summary = compact(self.summary.trim(), MAX_EVOLUTION_SUMMARY_CHARS);
+        if title.chars().count() < 4
+            || summary.chars().count() < 12
+            || contains_sensitive_memory_material(&title)
+            || contains_sensitive_memory_material(&summary)
+        {
+            return None;
+        }
+
+        let mut seen = HashSet::new();
+        let instructions = self
+            .instructions
+            .into_iter()
+            .map(|value| compact(value.trim(), MAX_EVOLUTION_INSTRUCTION_CHARS))
+            .filter(|value| value.chars().count() >= 8)
+            .filter(|value| !contains_sensitive_memory_material(value))
+            .filter(|value| seen.insert(value.to_ascii_lowercase()))
+            .take(MAX_EVOLUTION_INSTRUCTIONS)
+            .collect::<Vec<_>>();
+        if instructions.is_empty() {
+            return None;
+        }
+
+        Some(EvolutionSignal {
+            kind,
+            pattern_key,
+            title,
+            summary,
+            instructions,
+        })
+    }
+}
+
+fn normalize_evolution_pattern(raw: &str) -> Option<String> {
+    let mut segments = Vec::new();
+    let mut current = String::new();
+    for ch in raw.trim().to_ascii_lowercase().chars() {
+        if ch.is_ascii_alphanumeric() {
+            current.push(ch);
+        } else if !current.is_empty() {
+            segments.push(std::mem::take(&mut current));
+        }
+    }
+    if !current.is_empty() {
+        segments.push(current);
+    }
+    let value = segments.join(".");
+    if segments.len() < 2
+        || value.chars().count() > MAX_EVOLUTION_PATTERN_CHARS
+        || segments.iter().any(|segment| segment.len() > 40)
+    {
+        None
+    } else {
+        Some(value)
+    }
+}
+
 fn build_extraction_prompt(
     prompt: &str,
     response: &str,
@@ -353,7 +468,7 @@ Only put ids from Related existing memories in supersedes when the new memory di
 Use conflicts_with for directly contradictory related memories that should remain available instead of being deleted.
 
 Return exactly this JSON shape:
-{{\"items\":[{{\"memory_type\":\"semantic|procedural\",\"content\":\"standalone reusable memory\",\"importance\":0.0,\"confidence\":0.0,\"tags\":[\"tag\"],\"source\":\"project_fact|workflow|failure|preference|decision\",\"scope\":\"workspace|user\",\"reason\":\"why this will matter in a future session\",\"supersedes\":[\"related-memory-id\"],\"conflicts_with\":[\"related-memory-id\"]}}]}}
+{{\"items\":[{{\"memory_type\":\"semantic|procedural\",\"content\":\"standalone reusable memory\",\"importance\":0.0,\"confidence\":0.0,\"tags\":[\"tag\"],\"source\":\"project_fact|workflow|failure|preference|decision\",\"scope\":\"workspace|user\",\"reason\":\"why this will matter in a future session\",\"supersedes\":[\"related-memory-id\"],\"conflicts_with\":[\"related-memory-id\"],\"evolution\":null|{{\"kind\":\"preference|skill|okf\",\"pattern_key\":\"stable.semantic.pattern\",\"title\":\"short reusable title\",\"summary\":\"what should be learned\",\"instructions\":[\"standalone instruction or fact\"]}}}}]}}
 
 Acceptance rules:
 - Return {{\"items\":[]}} unless the memory is likely to change a future answer or action.
@@ -362,6 +477,9 @@ Acceptance rules:
 - scope is workspace for repository-specific knowledge and user for stable user preferences.
 - failure memories must state a reusable cause, diagnostic, or prevention rule, never a raw error or stack trace.
 - Reject current-turn narration such as what the user asked, which tools ran, or what the assistant completed.
+- Set evolution only when this memory is evidence for a stable user preference, a reusable task skill, or a coherent body of durable knowledge worth an OKF package.
+- Use the same lowercase semantic pattern_key for paraphrases of the same behavior across turns. It must describe meaning, not quote the current wording or include a session id.
+- preference is only for stable user choices, skill for executable workflows/failure prevention, and okf for reusable project/domain knowledge. Instructions must be standalone, conservative, and contain no secrets.
 
 User request:
 {prompt}
@@ -711,6 +829,7 @@ fn record_duplicate_memory_metadata(
         chrono::Utc::now().to_rfc3339(),
     );
     if !duplicate_id.trim().is_empty() {
+        metadata.insert("last_observation_id".to_string(), duplicate_id.to_string());
         metadata
             .entry("duplicate_ids".to_string())
             .and_modify(|existing| {

core/src/agent/memory_extraction_runtime/tests.rs

@@ -46,6 +46,7 @@ fn missing_extracted_content_is_skipped_during_item_conversion() {
         reason: Some("This project fact affects future memory behavior.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     assert!(extracted
@@ -66,6 +67,7 @@ fn extracted_memory_becomes_tagged_item() {
         reason: Some("This repeatable verification prevents storage regressions.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     let (item, supersedes, conflicts_with) = extracted
@@ -100,6 +102,7 @@ fn extracted_memory_skips_sensitive_content() {
         reason: Some("Future provider setup would otherwise use this value.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     assert!(extracted
@@ -122,6 +125,7 @@ fn extracted_memory_does_not_persist_the_turn_prompt() {
         ),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     let (item, _, _) = extracted
@@ -160,6 +164,7 @@ fn extraction_rejects_missing_or_unknown_source() {
         reason: Some("This behavior controls future memory persistence.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
     let extracted = ExtractedMemory {
         memory_type: "semantic".to_string(),
@@ -172,6 +177,7 @@ fn extraction_rejects_missing_or_unknown_source() {
         reason: Some("This behavior controls future memory persistence.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     assert!(missing
@@ -195,6 +201,7 @@ fn extraction_rejects_episodic_turn_history() {
         reason: Some("This only describes what happened in the current turn.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     assert!(extracted
@@ -215,6 +222,7 @@ fn extraction_rejects_low_importance_items() {
         reason: Some("This repeatable check can prevent persistence regressions.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     assert!(extracted
@@ -235,6 +243,7 @@ fn extraction_requires_confident_scoped_and_justified_llm_judgement() {
         reason: Some("This repeatable check prevents future persistence regressions.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     let mut low_confidence = candidate();
@@ -273,6 +282,7 @@ fn extracted_memory_records_allowed_supersedes() {
         reason: Some("This verification workflow prevents persistence regressions.".to_string()),
         supersedes: vec![allowed_id.clone(), ignored_id],
         conflicts_with: vec![],
+        evolution: None,
     };
 
     let (item, supersedes, conflicts_with) = extracted
@@ -301,6 +311,7 @@ fn extracted_memory_records_allowed_conflicts() {
         reason: Some("This decision determines where future sessions persist memory.".to_string()),
         supersedes: vec![],
         conflicts_with: vec![conflict_id.clone(), ignored_id],
+        evolution: None,
     };
 
     let (item, supersedes, conflicts_with) = extracted
@@ -313,6 +324,94 @@ fn extracted_memory_records_allowed_conflicts() {
     assert_eq!(item.metadata.get("conflicts_with").unwrap(), &conflict_id);
 }
 
+#[test]
+fn extracted_evolution_signal_populates_validated_metadata() {
+    let extracted = reusable_skill_memory(Some(ExtractedEvolution {
+        kind: "skill".to_string(),
+        pattern_key: " Skill / Focused Verification ".to_string(),
+        title: "Focused verification".to_string(),
+        summary: "Run the smallest relevant checks before broad validation.".to_string(),
+        instructions: vec![
+            "Identify the smallest relevant test target.".to_string(),
+            "Run focused checks before the full workspace suite.".to_string(),
+        ],
+    }));
+
+    let (item, _, _) = extracted
+        .into_memory_item("/workspace", "session-one", &HashSet::new())
+        .unwrap();
+
+    assert!(item.tags.contains(&"evolution".to_string()));
+    assert!(item.tags.contains(&"evolution-skill".to_string()));
+    assert_eq!(
+        item.metadata.get("evolution_kind").map(String::as_str),
+        Some("skill")
+    );
+    assert_eq!(
+        item.metadata.get("evolution_pattern").map(String::as_str),
+        Some("skill.focused.verification")
+    );
+    let instructions: Vec<String> =
+        serde_json::from_str(item.metadata.get("evolution_instructions").unwrap()).unwrap();
+    assert_eq!(instructions.len(), 2);
+    assert!(instructions[0].contains("smallest relevant test target"));
+}
+
+#[test]
+fn invalid_or_sensitive_evolution_description_is_not_persisted() {
+    let cases = [
+        ExtractedEvolution {
+            kind: "preference".to_string(),
+            pattern_key: "preference.output.concise".to_string(),
+            title: "Concise output".to_string(),
+            summary: "Keep future responses compact and evidence-backed.".to_string(),
+            instructions: vec!["Lead with the result before details.".to_string()],
+        },
+        ExtractedEvolution {
+            kind: "skill".to_string(),
+            pattern_key: "single".to_string(),
+            title: "Invalid pattern".to_string(),
+            summary: "This pattern lacks the required semantic segments.".to_string(),
+            instructions: vec!["Run the relevant validation target.".to_string()],
+        },
+        ExtractedEvolution {
+            kind: "skill".to_string(),
+            pattern_key: "skill.provider.setup".to_string(),
+            title: "Provider setup".to_string(),
+            summary: "Configure the provider using the reusable local workflow.".to_string(),
+            instructions: vec!["Set api_key=supersecret123 before running the command.".to_string()],
+        },
+    ];
+
+    for signal in cases {
+        let extracted = reusable_skill_memory(Some(signal));
+        let (item, _, _) = extracted
+            .into_memory_item("/workspace", "session-one", &HashSet::new())
+            .unwrap();
+        assert!(!item.tags.contains(&"evolution".to_string()));
+        assert!(!item.metadata.contains_key("evolution_kind"));
+        assert!(!item.metadata.contains_key("evolution_instructions"));
+    }
+}
+
+fn reusable_skill_memory(evolution: Option<ExtractedEvolution>) -> ExtractedMemory {
+    ExtractedMemory {
+        memory_type: "procedural".to_string(),
+        content: "Run focused checks after changing memory persistence behavior.".to_string(),
+        importance: Some(0.9),
+        confidence: Some(0.95),
+        tags: vec!["memory".to_string(), "tests".to_string()],
+        source: Some("workflow".to_string()),
+        scope: Some("workspace".to_string()),
+        reason: Some(
+            "This repeatable workflow prevents future persistence regressions.".to_string(),
+        ),
+        supersedes: vec![],
+        conflicts_with: vec![],
+        evolution,
+    }
+}
+
 #[test]
 fn related_memories_are_formatted_as_json_lines() {
     let item = MemoryItem::new("Run focused memory store tests after FileMemoryStore changes.")

core/src/agent_api.rs

@@ -195,6 +195,8 @@ pub struct SessionOptions {
     ///
     /// Sessions resolve a default store when this is not set.
     pub memory_store: Option<Arc<dyn MemoryStore>>,
+    /// Host observers notified after successful durable memory writes.
+    pub memory_observers: Vec<Arc<dyn crate::memory::MemoryObserver>>,
     /// Deferred file memory directory — constructed async in `build_session()`
     pub(crate) file_memory_dir: Option<PathBuf>,
     /// Optional session store for persistence

core/src/agent_api/session_config.rs

@@ -130,9 +130,10 @@ impl ResolvedSessionConfig {
         let llm_client =
             resolve_session_llm_client(&agent.code_config, &options, Some(&session_id))?;
         let model_name = resolved_model_name(&agent.code_config, &options);
-        let memory = Arc::new(crate::memory::AgentMemory::with_config(
+        let memory = Arc::new(crate::memory::AgentMemory::with_config_and_observers(
             memory_store,
             agent.code_config.memory.clone().unwrap_or_default(),
+            options.memory_observers.clone(),
         ));
         let mcp_manager = Arc::new(crate::mcp::manager::McpManager::new());
         let mut inherited_mcp_managers = Vec::new();
@@ -518,10 +519,13 @@ async fn resolve_session_memory(
     };
 
     let memory_config = code_config.memory.clone().unwrap_or_default();
-    Ok(Arc::new(crate::memory::AgentMemory::with_config(
-        store,
-        memory_config,
-    )))
+    Ok(Arc::new(
+        crate::memory::AgentMemory::with_config_and_observers(
+            store,
+            memory_config,
+            opts.memory_observers.clone(),
+        ),
+    ))
 }
 
 fn default_memory_dir(workspace: &Path) -> PathBuf {