kmp_application/memory/
types.rs

1use kmp_domain::{
2    DimensionSelection, ResolutionTier, TemporalCoordinate, TemporalCursor, TemporalDirection,
3    TemporalWindow,
4};
5
6use crate::queries::{GetNodeDetailResult, GraphRelationshipView};
7
8pub const DEFAULT_TRACE_PAGE_ENTRIES: usize = 64;
9pub const MAX_TRACE_PAGE_ENTRIES: usize = 256;
10
11#[derive(Debug, Clone, PartialEq, Eq)]
12pub struct MemoryIngestCommand {
13    pub about: String,
14    pub memory: MemoryData,
15    pub provenance: Option<MemoryProvenanceData>,
16    pub idempotency_key: String,
17    pub dry_run: bool,
18}
19
20#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
21pub struct MemoryData {
22    pub dimensions: Vec<MemoryDimensionData>,
23    pub entries: Vec<MemoryEntryData>,
24    pub relations: Vec<MemoryRelationData>,
25    pub evidence: Vec<MemoryEvidenceData>,
26}
27
28#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
29pub struct MemoryDimensionData {
30    pub id: String,
31    pub kind: String,
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub title: Option<String>,
34    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
35    pub metadata: std::collections::BTreeMap<String, String>,
36}
37
38#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
39pub struct MemoryEntryData {
40    pub id: String,
41    pub kind: String,
42    pub text: String,
43    pub coordinates: Vec<MemoryCoordinateData>,
44    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
45    pub metadata: std::collections::BTreeMap<String, String>,
46}
47
48#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
49pub struct MemoryCoordinateData {
50    pub dimension: String,
51    pub scope_id: String,
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub occurred_at: Option<String>,
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub observed_at: Option<String>,
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub ingested_at: Option<String>,
58    #[serde(skip_serializing_if = "Option::is_none")]
59    pub valid_from: Option<String>,
60    #[serde(skip_serializing_if = "Option::is_none")]
61    pub valid_until: Option<String>,
62    #[serde(skip_serializing_if = "Option::is_none")]
63    pub sequence: Option<u32>,
64    #[serde(skip_serializing_if = "Option::is_none")]
65    pub rank: Option<u32>,
66    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
67    pub metadata: std::collections::BTreeMap<String, String>,
68}
69
70#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
71pub struct MemoryRelationData {
72    #[serde(rename = "from")]
73    pub source_ref: String,
74    #[serde(rename = "to")]
75    pub target_ref: String,
76    pub rel: String,
77    #[serde(rename = "class")]
78    pub semantic_class: String,
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub why: Option<String>,
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub evidence: Option<String>,
83    #[serde(skip_serializing_if = "Option::is_none")]
84    pub confidence: Option<String>,
85    #[serde(skip_serializing_if = "Option::is_none")]
86    pub sequence: Option<u32>,
87    #[serde(skip_serializing_if = "Option::is_none")]
88    pub motivation: Option<String>,
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub method: Option<String>,
91    #[serde(skip_serializing_if = "Option::is_none")]
92    pub decision_id: Option<String>,
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub caused_by_node_id: Option<String>,
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub coordinate: Option<MemoryCoordinateData>,
97}
98
99#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
100pub struct MemoryEvidenceData {
101    pub id: String,
102    pub supports: Vec<String>,
103    pub text: String,
104    #[serde(skip_serializing_if = "Option::is_none")]
105    pub source: Option<String>,
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub time: Option<String>,
108    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
109    pub metadata: std::collections::BTreeMap<String, String>,
110}
111
112#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
113pub struct MemoryProvenanceData {
114    pub source_kind: String,
115    pub source_agent: String,
116    pub observed_at: String,
117    pub correlation_id: Option<String>,
118    pub causation_id: Option<String>,
119}
120
121#[derive(Debug, Clone, PartialEq, Eq)]
122pub struct MemoryAcceptedCounts {
123    pub entries: usize,
124    pub relations: usize,
125    pub evidence: usize,
126}
127
128#[derive(Debug, Clone, PartialEq, Eq)]
129pub struct MemoryIngestOutcome {
130    pub about: String,
131    pub memory_id: String,
132    pub accepted: MemoryAcceptedCounts,
133    pub read_after_write_ready: bool,
134    pub warnings: Vec<String>,
135}
136
137#[derive(Debug, Clone, PartialEq, Eq)]
138pub struct WakeMemoryQuery {
139    pub about: String,
140    pub role: String,
141    pub intent: String,
142    pub dimensions: DimensionSelection,
143    pub token_budget: u32,
144    pub depth: u32,
145    pub max_tier: Option<ResolutionTier>,
146    /// Cap on surfaced proof.evidence entries (None = unbounded). When set and
147    /// the about has more, Wake returns the first `max_entries` and reports the
148    /// withheld count via proof.frontier_size so the client near-expands.
149    pub max_entries: Option<usize>,
150}
151
152#[derive(Debug, Clone, PartialEq, Eq)]
153pub struct AskMemoryQuery {
154    pub about: String,
155    pub question: String,
156    pub answer_policy: MemoryAnswerPolicy,
157    pub dimensions: DimensionSelection,
158    pub token_budget: u32,
159    pub depth: u32,
160    pub max_tier: Option<ResolutionTier>,
161    /// Cap on answer evidence entries after relevance filtering.
162    pub max_entries: Option<usize>,
163}
164
165#[derive(Debug, Clone, PartialEq, Eq)]
166pub struct TemporalMemoryQuery {
167    pub about: String,
168    pub direction: TemporalDirection,
169    pub cursor: TemporalCursor,
170    pub dimensions: DimensionSelection,
171    pub window: TemporalWindow,
172    pub limit_entries: Option<usize>,
173    pub include: TemporalIncludeOptions,
174    pub token_budget: u32,
175    pub depth: u32,
176    pub max_tier: Option<ResolutionTier>,
177}
178
179#[derive(Debug, Clone, PartialEq, Eq)]
180pub struct TraceMemoryQuery {
181    pub from: String,
182    pub to: String,
183    pub role: String,
184    pub token_budget: u32,
185    pub page: TracePageRequest,
186}
187
188#[derive(Debug, Clone, PartialEq, Eq, Default)]
189pub struct TracePageRequest {
190    pub entries: Option<usize>,
191    pub cursor: Option<usize>,
192}
193
194impl TracePageRequest {
195    pub fn offset(&self) -> usize {
196        self.cursor.unwrap_or_default()
197    }
198
199    pub fn entries_or_default(&self) -> usize {
200        self.entries.unwrap_or(DEFAULT_TRACE_PAGE_ENTRIES)
201    }
202}
203
204#[derive(Debug, Clone, PartialEq, Eq)]
205pub struct InspectMemoryQuery {
206    pub ref_id: String,
207    pub include_details: bool,
208    pub include_incoming: bool,
209    pub include_outgoing: bool,
210    pub include_raw: bool,
211}
212
213#[derive(Clone, PartialEq, Eq)]
214pub struct InspectMemoryResult {
215    pub detail: GetNodeDetailResult,
216    pub incoming: Vec<GraphRelationshipView>,
217    pub outgoing: Vec<GraphRelationshipView>,
218    pub raw_coordinates: Vec<TemporalCoordinate>,
219    pub include_details: bool,
220    pub include_raw: bool,
221}
222
223#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
224pub enum MemoryAnswerPolicy {
225    #[default]
226    EvidenceOrUnknown,
227    ShowConflicts,
228    BestEffort,
229}
230
231#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
232pub struct TemporalIncludeOptions {
233    pub evidence: bool,
234    pub relations: bool,
235    pub raw_refs: bool,
236}
237
238#[derive(Debug, Clone, PartialEq)]
239pub struct TemporalMemoryResult {
240    pub traversal: kmp_domain::TemporalTraversalResult,
241    pub source_bundle: kmp_domain::KmpBundle,
242    pub include: TemporalIncludeOptions,
243    pub quality: kmp_domain::BundleQualityMetrics,
244}
kmp_application/memory/types.rs

kmp_application/memory/
types.rs
