sh_layer3/memory_system/
mod.rs

1//! # Memory System
2//!
3//! 分层记忆系统：Working -> Session -> Project -> LongTerm
4
5pub mod file_backend;
6pub mod long_term;
7pub mod project;
8pub mod session;
9pub mod system;
10pub mod working;
11
12// Re-export unified system and implementations
13pub use file_backend::{FileBackend, JsonFileBackend, StorageContainer};
14pub use long_term::LongTermMemory;
15pub use project::ProjectMemory;
16pub use session::SessionMemory;
17pub use system::UnifiedMemorySystem;
18pub use working::WorkingMemory;
19
20use crate::types::{Layer3Result, MemoryEntry, MemoryQuery, MemoryTier};
21use async_trait::async_trait;
22use std::collections::HashMap;
23
24/// 记忆存储 trait
25///
26/// 定义单层记忆存储的核心接口。
27#[async_trait]
28pub trait MemoryStore: Send + Sync {
29    /// 记忆层级
30    fn tier(&self) -> MemoryTier;
31
32    /// 存储记忆条目
33    async fn store(&self, entry: MemoryEntry) -> Layer3Result<String>;
34
35    /// 获取记忆条目
36    async fn get(&self, id: &str) -> Layer3Result<Option<MemoryEntry>>;
37
38    /// 删除记忆条目
39    async fn delete(&self, id: &str) -> Layer3Result<bool>;
40
41    /// 查询记忆（按内容搜索）
42    async fn query(&self, query: &MemoryQuery) -> Layer3Result<Vec<MemoryEntry>>;
43
44    /// 列出所有记忆（按时间排序）
45    async fn list(&self, limit: Option<usize>) -> Layer3Result<Vec<MemoryEntry>>;
46
47    /// 清空该层所有记忆
48    async fn clear(&self) -> Layer3Result<usize>;
49
50    /// 记忆条目数量
51    async fn count(&self) -> Layer3Result<usize>;
52}
53
54/// 记忆系统 trait
55///
56/// 统一管理所有记忆层级的接口。
57#[async_trait]
58pub trait MemorySystem: Send + Sync {
59    /// 存储记忆到指定层级
60    async fn store(&self, tier: MemoryTier, content: String) -> Layer3Result<String>;
61
62    /// 从指定层级获取记忆
63    async fn get(&self, tier: MemoryTier, id: &str) -> Layer3Result<Option<MemoryEntry>>;
64
65    /// 跨层级查询记忆
66    ///
67    /// 默认从 Working -> Session -> Project -> LongTerm 依次查询
68    async fn query_all(&self, query: &MemoryQuery) -> Layer3Result<Vec<MemoryEntry>>;
69
70    /// 在指定层级查询
71    async fn query(&self, tier: MemoryTier, query: &MemoryQuery) -> Layer3Result<Vec<MemoryEntry>>;
72
73    /// 删除指定层级记忆
74    async fn delete(&self, tier: MemoryTier, id: &str) -> Layer3Result<bool>;
75
76    /// 清空指定层级
77    async fn clear(&self, tier: MemoryTier) -> Layer3Result<usize>;
78
79    /// 获取层级统计
80    async fn stats(&self) -> Layer3Result<HashMap<MemoryTier, usize>>;
81}
82
83/// 记忆重要性评估 trait
84pub trait ImportanceScorer: Send + Sync {
85    /// 计算记忆重要性分数 (0.0-1.0)
86    fn score(&self, entry: &MemoryEntry) -> f32;
87}
88
89/// 记忆衰减策略 trait
90///
91/// 定义记忆如何随时间衰减重要性。
92pub trait DecayPolicy: Send + Sync {
93    /// 计算衰减后的重要性
94    fn decay(&self, entry: &MemoryEntry, current_time: chrono::DateTime<chrono::Utc>) -> f32;
95
96    /// 是否应该清理该记忆
97    fn should_evict(&self, entry: &MemoryEntry) -> bool;
98}
99
100/// 默认衰减策略：基于时间和访问频率
101pub struct TimeBasedDecay {
102    /// 衰减率（每天）
103    decay_rate: f32,
104    /// 最低保留重要性
105    min_threshold: f32,
106}
107
108impl TimeBasedDecay {
109    pub fn new(decay_rate: f32, min_threshold: f32) -> Self {
110        Self {
111            decay_rate,
112            min_threshold,
113        }
114    }
115}
116
117impl Default for TimeBasedDecay {
118    fn default() -> Self {
119        Self {
120            decay_rate: 0.1,
121            min_threshold: 0.1,
122        }
123    }
124}
125
126impl DecayPolicy for TimeBasedDecay {
127    fn decay(&self, entry: &MemoryEntry, current_time: chrono::DateTime<chrono::Utc>) -> f32 {
128        let days_since_access = (current_time - entry.last_accessed).num_days() as f32;
129        let decayed = entry.importance * (1.0 - self.decay_rate * days_since_access);
130        decayed.max(0.0)
131    }
132
133    fn should_evict(&self, entry: &MemoryEntry) -> bool {
134        entry.importance < self.min_threshold
135    }
136}
137
138#[cfg(test)]
139mod tests {
140    use super::*;
141
142    #[test]
143    fn test_decay_policy_default() {
144        let decay = TimeBasedDecay::default();
145        assert_eq!(decay.decay_rate, 0.1);
146        assert_eq!(decay.min_threshold, 0.1);
147    }
148}
sh_layer3/memory_system/mod.rs

sh_layer3/memory_system/
mod.rs
