Skip to main content

second_brain_core/
schema.rs

1use chrono::{DateTime, Utc};
2use serde::{Deserialize, Serialize};
3use uuid::Uuid;
4
5fn epoch() -> DateTime<Utc> {
6    DateTime::UNIX_EPOCH
7}
8
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
10#[serde(rename_all = "snake_case")]
11pub enum MemoryType {
12    Episodic,
13    Semantic,
14    Procedural,
15    Decision,
16    Architecture,
17    Debugging,
18    Task,
19    Question,
20}
21
22/// Sources written through `remember` (over MCP, the HTTP API default,
23/// `sb remember`, the ask service and its autonomous trigger) or from
24/// Claude's own memory files, rather than mined from a transcript.
25/// Consolidation must leave these alone: a paraphrase of an explicit note
26/// loses exactly the wording its author chose.
27pub const EXPLICIT_SOURCES: &[&str] = &[
28    "mcp-direct",
29    "api",
30    "cli",
31    "ask",
32    "ask-auto",
33    "claude-memory",
34];
35
36/// SQL fragment over `$col` admitting only sources consolidation may
37/// distill: neither distillates themselves nor the explicit sources. The
38/// literal must list exactly `EXPLICIT_SOURCES`; a test enforces it.
39macro_rules! explicit_sources_list {
40    () => {
41        "'mcp-direct', 'api', 'cli', 'ask', 'ask-auto', 'claude-memory'"
42    };
43}
44macro_rules! distillable_source {
45    ($col:literal) => {
46        concat!(
47            $col,
48            " NOT IN ('consolidation', ",
49            $crate::schema::explicit_sources_list!(),
50            ")"
51        )
52    };
53}
54pub(crate) use {distillable_source, explicit_sources_list};
55
56#[derive(Debug, Clone, Serialize, Deserialize)]
57pub struct Memory {
58    pub id: Uuid,
59    pub content: String,
60    pub embedding: Vec<f32>,
61    pub memory_type: MemoryType,
62    pub confidence: f32,
63    pub created_at: DateTime<Utc>,
64    pub last_accessed: DateTime<Utc>,
65    pub access_count: u32,
66    pub source: String,
67    pub source_id: String,
68    #[serde(default)]
69    pub project_path: Option<String>,
70    #[serde(default)]
71    pub machine_id: String,
72    #[serde(default = "epoch")]
73    pub updated_at: DateTime<Utc>,
74    /// LLM-generated chunk context for contextual retrieval; indexed and
75    /// embedded together with `content`, backfilled nightly.
76    #[serde(default)]
77    pub context: Option<String>,
78    #[serde(default)]
79    pub conversation_id: Option<Uuid>,
80    #[serde(default)]
81    pub tier: Tier,
82    /// Cold-tier segment id once archived; content is then a stub and the
83    /// embedding is dropped from the row.
84    #[serde(default)]
85    pub archived_segment: Option<String>,
86    /// Zep-style soft invalidation: a superseded memory stays in the store
87    /// but leaves the retrieval indexes.
88    #[serde(default)]
89    pub superseded_by: Option<Uuid>,
90    /// Set when `forget` retired the memory: it is archived like a
91    /// consolidated raw but must never be restored with them.
92    #[serde(default)]
93    pub retired_reason: Option<String>,
94}
95
96#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
97#[serde(rename_all = "snake_case")]
98pub enum Tier {
99    #[default]
100    Hot,
101    Archived,
102}
103
104#[derive(Debug, Clone, Serialize, Deserialize)]
105pub struct Entity {
106    pub id: Uuid,
107    pub name: String,
108    pub entity_type: String,
109    pub embedding: Vec<f32>,
110    pub aliases: Vec<String>,
111}
112
113#[derive(Debug, Clone, Serialize, Deserialize)]
114pub struct Conversation {
115    pub id: Uuid,
116    pub source: String,
117    pub machine_id: String,
118    pub started_at: DateTime<Utc>,
119    pub project_path: Option<String>,
120}
121
122#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
123#[serde(rename_all = "snake_case")]
124pub enum RelationType {
125    RelatesTo,
126    Mentions,
127    DerivedFrom,
128    Contradicts,
129    Reinforces,
130    Supersedes,
131    DistilledFrom,
132}
133
134#[derive(Debug, Clone, Serialize, Deserialize)]
135pub struct Relation {
136    pub from_id: Uuid,
137    pub to_id: Uuid,
138    pub relation_type: RelationType,
139    pub strength: f32,
140    pub context: Option<String>,
141}
142
143impl Memory {
144    pub fn new(
145        content: String,
146        memory_type: MemoryType,
147        source: String,
148        source_id: String,
149    ) -> Self {
150        let now = Utc::now();
151        Self {
152            id: Uuid::new_v4(),
153            content,
154            embedding: Vec::new(),
155            memory_type,
156            confidence: 1.0,
157            created_at: now,
158            last_accessed: now,
159            access_count: 0,
160            source,
161            source_id,
162            project_path: None,
163            machine_id: String::new(),
164            updated_at: now,
165            context: None,
166            conversation_id: None,
167            tier: Tier::Hot,
168            archived_segment: None,
169            superseded_by: None,
170            retired_reason: None,
171        }
172    }
173
174    pub fn with_project_path(mut self, path: Option<String>) -> Self {
175        self.project_path = path;
176        self
177    }
178
179    pub fn with_machine_id(mut self, machine_id: String) -> Self {
180        self.machine_id = machine_id;
181        self
182    }
183}
184
185impl Entity {
186    pub fn new(name: String, entity_type: String) -> Self {
187        Self {
188            id: Uuid::new_v4(),
189            name,
190            entity_type,
191            embedding: Vec::new(),
192            aliases: Vec::new(),
193        }
194    }
195}
196
197#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
198#[serde(rename_all = "snake_case")]
199pub enum SyncOp {
200    Create,
201    Update,
202    Delete,
203}
204
205#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
206#[serde(rename_all = "snake_case")]
207pub enum SyncNodeType {
208    Memory,
209    Entity,
210    Conversation,
211    Relation,
212    Distillation,
213}
214
215/// The record that a memory has already been distilled. Without this on the
216/// wire only the distilled Memory replicates, never the fact that the source
217/// was consumed, so every peer re-distills the same memories against the same
218/// shared GPU.
219#[derive(Debug, Clone, Serialize, Deserialize)]
220pub struct Distillation {
221    pub memory_id: Uuid,
222    pub distilled_id: Option<Uuid>,
223    pub distilled_at: Option<DateTime<Utc>>,
224    pub model: Option<String>,
225    pub status: String,
226}
227
228#[derive(Debug, Clone, Serialize, Deserialize)]
229pub struct SyncEntry {
230    pub id: String,
231    pub local_seq: i64,
232    pub origin_machine_id: String,
233    pub origin_seq: i64,
234    pub op: SyncOp,
235    pub node_type: SyncNodeType,
236    pub node_id: String,
237    pub timestamp: DateTime<Utc>,
238    pub data: Option<String>,
239}
240
241/// Wire form of a sync-log entry: same fields as SyncEntry but with `data`
242/// parsed to JSON. Lives in core so StoreAdmin::apply_record can take it
243/// without core depending on the sync crate.
244#[derive(Debug, Clone, Serialize, Deserialize)]
245pub struct SyncRecord {
246    pub local_seq: u64,
247    pub origin_machine_id: String,
248    pub origin_seq: u64,
249    pub op: SyncOp,
250    pub node_type: SyncNodeType,
251    pub node_id: String,
252    pub timestamp: DateTime<Utc>,
253    pub data: Option<serde_json::Value>,
254}
255
256#[derive(Debug, Clone, Serialize, Deserialize)]
257pub struct SyncState {
258    pub peer_id: String,
259    pub last_seq: u64,
260    pub last_sync_at: DateTime<Utc>,
261}
262
263#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
264pub struct CompactStats {
265    pub groups_with_duplicates: u64,
266    pub rows_deleted: u64,
267    pub max_local_seq_before: u64,
268    pub max_local_seq_after: u64,
269}