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}
162
163#[derive(Debug, Clone, PartialEq, Eq)]
164pub struct TemporalMemoryQuery {
165    pub about: String,
166    pub direction: TemporalDirection,
167    pub cursor: TemporalCursor,
168    pub dimensions: DimensionSelection,
169    pub window: TemporalWindow,
170    pub limit_entries: Option<usize>,
171    pub include: TemporalIncludeOptions,
172    pub token_budget: u32,
173    pub depth: u32,
174    pub max_tier: Option<ResolutionTier>,
175}
176
177#[derive(Debug, Clone, PartialEq, Eq)]
178pub struct TraceMemoryQuery {
179    pub from: String,
180    pub to: String,
181    pub role: String,
182    pub token_budget: u32,
183    pub page: TracePageRequest,
184}
185
186#[derive(Debug, Clone, PartialEq, Eq, Default)]
187pub struct TracePageRequest {
188    pub entries: Option<usize>,
189    pub cursor: Option<usize>,
190}
191
192impl TracePageRequest {
193    pub fn offset(&self) -> usize {
194        self.cursor.unwrap_or_default()
195    }
196
197    pub fn entries_or_default(&self) -> usize {
198        self.entries.unwrap_or(DEFAULT_TRACE_PAGE_ENTRIES)
199    }
200}
201
202#[derive(Debug, Clone, PartialEq, Eq)]
203pub struct InspectMemoryQuery {
204    pub ref_id: String,
205    pub include_details: bool,
206    pub include_incoming: bool,
207    pub include_outgoing: bool,
208    pub include_raw: bool,
209}
210
211#[derive(Clone, PartialEq, Eq)]
212pub struct InspectMemoryResult {
213    pub detail: GetNodeDetailResult,
214    pub incoming: Vec<GraphRelationshipView>,
215    pub outgoing: Vec<GraphRelationshipView>,
216    pub raw_coordinates: Vec<TemporalCoordinate>,
217    pub include_details: bool,
218    pub include_raw: bool,
219}
220
221#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
222pub enum MemoryAnswerPolicy {
223    #[default]
224    EvidenceOrUnknown,
225    ShowConflicts,
226    BestEffort,
227}
228
229#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
230pub struct TemporalIncludeOptions {
231    pub evidence: bool,
232    pub relations: bool,
233    pub raw_refs: bool,
234}
235
236#[derive(Debug, Clone, PartialEq)]
237pub struct TemporalMemoryResult {
238    pub traversal: kmp_domain::TemporalTraversalResult,
239    pub source_bundle: kmp_domain::KmpBundle,
240    pub include: TemporalIncludeOptions,
241    pub quality: kmp_domain::BundleQualityMetrics,
242}
kmp_application/memory/types.rs

kmp_application/memory/
types.rs
