hippmem_core/model/
understanding.rs

1//! MemoryUnderstanding and all understanding frames.
2//!
3//! Corresponds to 02#memoryunderstanding, 02#understanding-frames.
4
5use crate::ids::MemoryId;
6use crate::model::unit::TextSpan;
7use crate::score::UnitScore;
8use crate::time::Timestamp;
9use serde::{Deserialize, Serialize};
10
11/// Memory understanding: the structured understanding result that an algorithm or model produces for content.
12///
13/// Dimension layering:
14/// - Basic immediate dimensions (indexed stage): entities, topics, explicit causal_claims
15/// - Strong semantic dimensions (enriched stage): goals, preferences, emotions, decisions, implicit causal_claims, contradictions
16///
17/// Corresponds to 02#memoryunderstanding, traceable to whitepaper §5.4.
18#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
19pub struct MemoryUnderstanding {
20    /// Entity mention list.
21    pub entities: Vec<EntityMention>,
22    /// Event frame list.
23    pub events: Vec<EventFrame>,
24    /// Goal frame list (strong semantic dimension).
25    pub goals: Vec<GoalFrame>,
26    /// Decision frame list (strong semantic dimension).
27    pub decisions: Vec<DecisionFrame>,
28    /// Preference frame list (strong semantic dimension).
29    pub preferences: Vec<PreferenceFrame>,
30    /// Emotion frame list (strong semantic dimension).
31    pub emotions: Vec<EmotionFrame>,
32    /// Causal claim list.
33    pub causal_claims: Vec<CausalClaim>,
34    /// Contradiction hint list (strong semantic dimension).
35    pub contradictions: Vec<ContradictionHint>,
36    /// Preliminary topics (basic immediate dimension).
37    pub topics: Vec<TopicTag>,
38    /// Overall importance.
39    pub importance: UnitScore,
40    /// Confidence in the overall understanding.
41    pub confidence: UnitScore,
42}
43
44// ── EntityMention ──
45
46/// Entity mention: a person/project/library/file/organization/concept mentioned in text, along with its position and type.
47#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
48pub struct EntityMention {
49    /// The entity's surface form in the source text.
50    pub text: String,
51    /// Canonical name (used to generate entity_key).
52    pub canonical: String,
53    /// Entity type.
54    pub entity_type: EntityType,
55    /// Position in the source text.
56    pub span: Option<TextSpan>,
57    /// Confidence.
58    pub confidence: UnitScore,
59}
60
61/// Entity type enum.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
63pub enum EntityType {
64    /// Person
65    Person,
66    /// Project
67    Project,
68    /// Library
69    Library,
70    /// File
71    File,
72    /// Organization
73    Org,
74    /// Concept
75    Concept,
76    /// Other
77    Other,
78}
79
80// ── EventFrame ──
81
82/// Event frame: the time, participants, action, and outcome of an event.
83#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
84pub struct EventFrame {
85    /// Action/predicate.
86    pub action: String,
87    /// Canonical names of participating entities.
88    pub participants: Vec<String>,
89    /// Occurrence time.
90    pub occurred_at: Option<Timestamp>,
91    /// Outcome.
92    pub outcome: Option<String>,
93    /// Confidence.
94    pub confidence: UnitScore,
95}
96
97// ── GoalFrame ──
98
99/// Goal frame: user/project goal, constraints, and status. A strong semantic dimension.
100#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
101pub struct GoalFrame {
102    /// Goal description.
103    pub description: String,
104    /// Goal status.
105    pub status: GoalStatus,
106    /// Constraints.
107    pub constraints: Vec<String>,
108    /// Confidence.
109    pub confidence: UnitScore,
110}
111
112/// Goal status enum.
113#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
114pub enum GoalStatus {
115    /// In progress
116    Active,
117    /// Achieved
118    Achieved,
119    /// Abandoned
120    Abandoned,
121    /// Blocked
122    Blocked,
123    /// Unknown
124    Unknown,
125}
126
127// ── DecisionFrame ──
128
129/// Decision frame: the content, rationale, time, and whether reverted of a decision. A strong semantic dimension.
130#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
131pub struct DecisionFrame {
132    /// What was decided.
133    pub decision: String,
134    /// Decision rationale.
135    pub rationale: Option<String>,
136    /// Decision time.
137    pub decided_at: Option<Timestamp>,
138    /// Whether it has been reverted.
139    pub reverted: bool,
140    /// Confidence.
141    pub confidence: UnitScore,
142}
143
144// ── PreferenceFrame ──
145
146/// Preference frame: preference object, polarity (like/dislike), strength, and validity. A strong semantic dimension.
147#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
148pub struct PreferenceFrame {
149    /// Preference object.
150    pub object: String,
151    /// Polarity direction.
152    pub polarity: Polarity,
153    /// Strength.
154    pub strength: UnitScore,
155    /// Whether still valid (can be negated by a Correction).
156    pub still_valid: bool,
157    /// Confidence.
158    pub confidence: UnitScore,
159}
160
161/// Polarity direction enum.
162#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
163pub enum Polarity {
164    /// Like
165    Like,
166    /// Dislike
167    Dislike,
168    /// Neutral
169    Neutral,
170}
171
172// ── EmotionFrame ──
173
174/// Emotion frame: emotion kind, intensity, and trigger object. A strong semantic dimension.
175#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
176pub struct EmotionFrame {
177    /// Emotion kind.
178    pub emotion: EmotionKind,
179    /// Intensity.
180    pub intensity: UnitScore,
181    /// Trigger object.
182    pub trigger: Option<String>,
183    /// Confidence.
184    pub confidence: UnitScore,
185}
186
187/// Fixed emotion category, mapped to emotion_keys (u8). The first version uses basic categories.
188#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
189pub enum EmotionKind {
190    /// Joy
191    Joy,
192    /// Sadness
193    Sadness,
194    /// Anger
195    Anger,
196    /// Fear
197    Fear,
198    /// Surprise
199    Surprise,
200    /// Disgust
201    Disgust,
202    /// Frustration
203    Frustration,
204    /// Anxiety
205    Anxiety,
206    /// Satisfaction
207    Satisfaction,
208    /// Neutral
209    Neutral,
210    /// Other
211    Other,
212}
213
214// ── CausalClaim ──
215
216/// Causal claim: a directed cause→effect assertion with confidence and evidence.
217#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
218pub struct CausalClaim {
219    /// Cause.
220    pub cause: String,
221    /// Effect.
222    pub effect: String,
223    /// Causal kind (explicit/implicit).
224    pub kind: CausalKind,
225    /// Position of the evidence in the source text.
226    pub evidence_span: Option<TextSpan>,
227    /// Confidence.
228    pub confidence: UnitScore,
229}
230
231/// Causal kind: explicit (conjunction hit) / implicit (model inferred).
232#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
233pub enum CausalKind {
234    /// Explicit causality (conjunction hit)
235    Explicit,
236    /// Implicit causality (model inferred)
237    Implicit,
238}
239
240// ── ContradictionHint ──
241
242/// Contradiction hint: a hint pointing to two potentially conflicting pieces of information. A strong semantic dimension.
243#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
244pub struct ContradictionHint {
245    /// The claim in this memory.
246    pub statement_a: String,
247    /// The suspected conflicting old memory (may be unknown at write time).
248    pub conflicts_with: Option<MemoryId>,
249    /// Conflict description.
250    pub note: String,
251    /// Confidence.
252    pub confidence: UnitScore,
253}
254
255// ── TopicTag ──
256
257/// Topic tag: a preliminary topic marker (basic immediate dimension).
258#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
259pub struct TopicTag {
260    /// Topic label (canonical).
261    pub label: String,
262    /// Confidence.
263    pub confidence: UnitScore,
264}
hippmem_core/model/understanding.rs

hippmem_core/model/
understanding.rs
