1use chrono::{DateTime, Utc};
2
3#[derive(Clone, Debug, Default)]
4pub struct MemoryScope {
5 pub session_ids: Option<Vec<String>>,
6 pub tiers: Option<Vec<String>>,
7 pub from_utc: Option<DateTime<Utc>>,
8 pub to_utc: Option<DateTime<Utc>>,
9}
10
11#[derive(Clone, Copy, Debug, Default)]
12pub struct MemoryAvecState {
13 pub stability: f32,
14 pub friction: f32,
15 pub logic: f32,
16 pub autonomy: f32,
17}
18
19#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
20pub enum MemoryFallbackPolicy {
21 Never,
22 #[default]
23 OnEmpty,
24 Always,
25}
26
27#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
28pub enum MemoryStrictnessMode {
29 Precision,
30 #[default]
31 Balanced,
32 Recall,
33}
34
35#[derive(Clone, Debug)]
36pub struct MemoryRecallRequest {
37 pub scope: MemoryScope,
38 pub current_avec: Option<MemoryAvecState>,
39 pub query_text: Option<String>,
40 pub limit: usize,
41 pub alpha: f32,
42 pub beta: f32,
43 pub fallback_policy: MemoryFallbackPolicy,
44 pub strictness: MemoryStrictnessMode,
45 pub include_explain: bool,
46}
47
48impl Default for MemoryRecallRequest {
49 fn default() -> Self {
50 Self {
51 scope: MemoryScope::default(),
52 current_avec: None,
53 query_text: None,
54 limit: 20,
55 alpha: 0.7,
56 beta: 0.3,
57 fallback_policy: MemoryFallbackPolicy::OnEmpty,
58 strictness: MemoryStrictnessMode::Balanced,
59 include_explain: false,
60 }
61 }
62}
63
64#[derive(Clone, Debug, Default)]
65pub struct MemoryMetricRange {
66 pub min: Option<f32>,
67 pub max: Option<f32>,
68}
69
70#[derive(Clone, Debug, Default)]
71pub struct MemoryFilter {
72 pub has_embedding: Option<bool>,
73 pub embedding_model: Option<String>,
74 pub psi: Option<MemoryMetricRange>,
75 pub rho: Option<MemoryMetricRange>,
76 pub kappa: Option<MemoryMetricRange>,
77 pub text_contains: Option<String>,
78}
79
80#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
81pub enum MemorySortField {
82 #[default]
83 Timestamp,
84 UpdatedAt,
85 Psi,
86 Rho,
87 Kappa,
88}
89
90#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
91pub enum MemorySortDirection {
92 Asc,
93 #[default]
94 Desc,
95}
96
97#[derive(Clone, Debug)]
98pub struct MemoryFindRequest {
99 pub scope: MemoryScope,
100 pub filter: MemoryFilter,
101 pub limit: usize,
102 pub cursor: Option<String>,
103 pub sort_field: MemorySortField,
104 pub sort_direction: MemorySortDirection,
105}
106
107impl Default for MemoryFindRequest {
108 fn default() -> Self {
109 Self {
110 scope: MemoryScope::default(),
111 filter: MemoryFilter::default(),
112 limit: 50,
113 cursor: None,
114 sort_field: MemorySortField::Timestamp,
115 sort_direction: MemorySortDirection::Desc,
116 }
117 }
118}
119
120#[derive(Clone, Debug, Default)]
121pub struct MemoryNode {
122 pub raw: String,
123 pub session_id: String,
124 pub tier: String,
125 pub timestamp: DateTime<Utc>,
126 pub compression_depth: i32,
127 pub parent_node_id: Option<String>,
128 pub sync_key: String,
129 pub context_summary: Option<String>,
130 pub embedding_model: Option<String>,
131 pub embedding_dimensions: Option<usize>,
132 pub embedded_at: Option<DateTime<Utc>>,
133 pub rho: f32,
134 pub kappa: f32,
135 pub psi: f32,
136 pub user_avec: MemoryAvecState,
137 pub model_avec: MemoryAvecState,
138 pub compression_avec: Option<MemoryAvecState>,
139 pub updated_at: DateTime<Utc>,
140}
141
142#[derive(Clone, Debug, Default)]
143pub struct MemoryFindResponse {
144 pub retrieved: usize,
145 pub has_more: bool,
146 pub next_cursor: Option<String>,
147 pub nodes: Vec<MemoryNode>,
148 pub node_sync_keys: Vec<String>,
149}
150
151#[derive(Clone, Debug, Default)]
152pub struct MemoryRecallResponse {
153 pub retrieved: usize,
154 pub next_cursor: Option<String>,
155 pub has_more: bool,
156 pub retrieval_path: Option<String>,
157 pub fallback_triggered: bool,
158 pub fallback_reason: Option<String>,
159 pub nodes: Vec<MemoryNode>,
160 pub node_sync_keys: Vec<String>,
161}
162
163#[derive(Clone, Debug)]
164pub struct MemoryStoreRequest {
165 pub session_id: String,
166 pub raw_node: String,
167}
168
169#[derive(Clone, Debug, Default)]
170pub struct MemoryStoreResponse {
171 pub node_id: String,
172 pub psi: f32,
173 pub valid: bool,
174 pub validation_error: Option<String>,
175}
176
177#[derive(Clone, Debug, Default)]
178pub struct MemoryAggregateRequest {
179 pub scope: MemoryScope,
180 pub max_groups: usize,
181 pub max_nodes: usize,
182}
183
184#[derive(Clone, Debug, Default)]
185pub struct MemoryAggregateResponse {
186 pub total_groups: usize,
187 pub scanned_nodes: usize,
188}
189
190#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
191pub enum MemoryTransformOperation {
192 #[default]
193 EmbedBackfill,
194 ReindexEmbeddings,
195}
196
197#[derive(Clone, Debug)]
198pub struct MemoryTransformRequest {
199 pub scope: MemoryScope,
200 pub operation: MemoryTransformOperation,
201 pub dry_run: bool,
202 pub batch_size: usize,
203 pub max_nodes: usize,
204 pub provider_id: Option<String>,
205 pub model: Option<String>,
206}
207
208impl Default for MemoryTransformRequest {
209 fn default() -> Self {
210 Self {
211 scope: MemoryScope::default(),
212 operation: MemoryTransformOperation::EmbedBackfill,
213 dry_run: true,
214 batch_size: 100,
215 max_nodes: 5000,
216 provider_id: None,
217 model: None,
218 }
219 }
220}
221
222#[derive(Clone, Debug, Default)]
223pub struct MemoryTransformResponse {
224 pub scanned: usize,
225 pub selected: usize,
226 pub updated: usize,
227 pub skipped: usize,
228 pub failed: usize,
229 pub duplicate: usize,
230 pub failures: Vec<String>,
231}
232
233#[derive(Clone, Debug, Default)]
234pub struct MemoryRollupRequest {
235 pub scope: MemoryScope,
236 pub max_days: usize,
237 pub max_nodes: usize,
238}
239
240#[derive(Clone, Debug, Default)]
241pub struct MemoryRollupResponse {
242 pub total_groups: usize,
243 pub scanned_nodes: usize,
244}
245
246#[derive(Clone, Debug, Default)]
247pub struct MemorySchemaResponse {
248 pub schema_version: String,
249 pub sort_fields: Vec<String>,
250 pub filter_fields: Vec<String>,
251 pub group_by_fields: Vec<String>,
252 pub fallback_policies: Vec<String>,
253 pub strictness_modes: Vec<String>,
254 pub transform_operations: Vec<String>,
255}