deepstrike_core/mm/
mod.rs

1//! Memory-management paging decisions (Phase 4) and long-term memory management (Phase 7).
2//!
3//! The kernel decides **when** to page working context out/in; SDKs perform **how**
4//! (durable store, embedding search, idle pipeline). No I/O in this module.
5//!
6//! Phase 7 extends this module with memory classification and validation rules.
7
8use crate::context::pressure::PressureAction;
9use serde::{Deserialize, Serialize};
10
11pub mod handle;
12pub mod memory;
13
14pub use handle::{
15    plan_eviction, plan_spool, EvictionOp, EvictionPlan, Handle, HandleId, HandleKind, HandleTable,
16    Residency, SpoolDecision,
17};
18
19/// Long-term tier hint for a page-out event (SDK maps to durable vs semantic store).
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(rename_all = "snake_case")]
22pub enum MemoryTierHint {
23    /// History compression archive — default durable/session store.
24    Durable,
25    /// Sprint renewal / handoff — semantic long-term pipeline.
26    Semantic,
27}
28
29impl MemoryTierHint {
30    pub fn label(self) -> &'static str {
31        match self {
32            Self::Durable => "durable",
33            Self::Semantic => "semantic",
34        }
35    }
36}
37
38/// Map a pressure-driven compression action to the recommended long-term tier.
39pub fn tier_hint_for_compress(action: PressureAction) -> MemoryTierHint {
40    match action {
41        PressureAction::ContextCollapse | PressureAction::AutoCompact => MemoryTierHint::Semantic,
42        _ => MemoryTierHint::Durable,
43    }
44}
45
46/// Parsed arguments for a page-in meta-tool call. Retained as the payload type for
47/// [`crate::syscall::Syscall::PageIn`]; the request-extraction helper that used to build these
48/// from live tool calls was removed when the automatic memory/knowledge tool-call page-in path
49/// was retired (that content now flows through the normal tool-result → history path instead —
50/// see `apply_page_in`'s doc comment).
51#[derive(Debug, Clone, Default)]
52pub struct PageInRequest {
53    pub call_id: String,
54    pub tool: String,
55    pub query: String,
56    pub top_k: u32,
57}
58
59/// One knowledge entry supplied by the SDK after a long-term fetch (page-in).
60#[derive(Debug, Clone, Serialize, Deserialize)]
61pub struct PageInEntry {
62    pub content: String,
63    #[serde(default, skip_serializing_if = "Option::is_none")]
64    pub tokens: Option<u32>,
65    #[serde(default, skip_serializing_if = "Option::is_none")]
66    pub source: Option<String>,
67    /// K1: entry identity — a keyed page-in upserts instead of appending a duplicate.
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub key: Option<String>,
70    /// K1: pinned entries are exempt from the K2 budget sweep.
71    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
72    pub pinned: bool,
73}
74
75#[cfg(test)]
76mod tests {
77    use super::*;
78
79    #[test]
80    fn tier_hint_maps_auto_compact_to_semantic() {
81        assert_eq!(
82            tier_hint_for_compress(PressureAction::AutoCompact),
83            MemoryTierHint::Semantic
84        );
85        assert_eq!(
86            tier_hint_for_compress(PressureAction::SnipCompact),
87            MemoryTierHint::Durable
88        );
89    }
90
91}
deepstrike_core/mm/mod.rs

deepstrike_core/mm/
mod.rs
