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    /// When the session this knowledge came from happened: the transcript
95    /// line's time, or for a distillate the latest of its raws. None means
96    /// no evidence survives, which must be shown as unknown, never guessed
97    /// from `created_at` (that is the ingest or distill time).
98    #[serde(default)]
99    pub session_at: Option<DateTime<Utc>>,
100}
101
102#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
103#[serde(rename_all = "snake_case")]
104pub enum Tier {
105    #[default]
106    Hot,
107    Archived,
108}
109
110#[derive(Debug, Clone, Serialize, Deserialize)]
111pub struct Entity {
112    pub id: Uuid,
113    pub name: String,
114    pub entity_type: String,
115    pub embedding: Vec<f32>,
116    pub aliases: Vec<String>,
117}
118
119#[derive(Debug, Clone, Serialize, Deserialize)]
120pub struct Conversation {
121    pub id: Uuid,
122    pub source: String,
123    pub machine_id: String,
124    pub started_at: DateTime<Utc>,
125    pub project_path: Option<String>,
126}
127
128#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
129#[serde(rename_all = "snake_case")]
130pub enum RelationType {
131    RelatesTo,
132    Mentions,
133    DerivedFrom,
134    Contradicts,
135    Reinforces,
136    Supersedes,
137    DistilledFrom,
138}
139
140#[derive(Debug, Clone, Serialize, Deserialize)]
141pub struct Relation {
142    pub from_id: Uuid,
143    pub to_id: Uuid,
144    pub relation_type: RelationType,
145    pub strength: f32,
146    pub context: Option<String>,
147}
148
149impl Memory {
150    pub fn new(
151        content: String,
152        memory_type: MemoryType,
153        source: String,
154        source_id: String,
155    ) -> Self {
156        let now = Utc::now();
157        Self {
158            id: Uuid::new_v4(),
159            content,
160            embedding: Vec::new(),
161            memory_type,
162            confidence: 1.0,
163            created_at: now,
164            last_accessed: now,
165            access_count: 0,
166            source,
167            source_id,
168            project_path: None,
169            machine_id: String::new(),
170            updated_at: now,
171            context: None,
172            conversation_id: None,
173            tier: Tier::Hot,
174            archived_segment: None,
175            superseded_by: None,
176            retired_reason: None,
177            session_at: None,
178        }
179    }
180
181    pub fn with_project_path(mut self, path: Option<String>) -> Self {
182        self.project_path = path;
183        self
184    }
185
186    pub fn with_machine_id(mut self, machine_id: String) -> Self {
187        self.machine_id = machine_id;
188        self
189    }
190}
191
192impl Entity {
193    pub fn new(name: String, entity_type: String) -> Self {
194        Self {
195            id: Uuid::new_v4(),
196            name,
197            entity_type,
198            embedding: Vec::new(),
199            aliases: Vec::new(),
200        }
201    }
202}
203
204#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
205#[serde(rename_all = "snake_case")]
206pub enum SyncOp {
207    Create,
208    Update,
209    Delete,
210}
211
212#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
213#[serde(rename_all = "snake_case")]
214pub enum SyncNodeType {
215    Memory,
216    Entity,
217    Conversation,
218    Relation,
219    Distillation,
220}
221
222/// The record that a memory has already been distilled. Without this on the
223/// wire only the distilled Memory replicates, never the fact that the source
224/// was consumed, so every peer re-distills the same memories against the same
225/// shared GPU.
226#[derive(Debug, Clone, Serialize, Deserialize)]
227pub struct Distillation {
228    pub memory_id: Uuid,
229    pub distilled_id: Option<Uuid>,
230    pub distilled_at: Option<DateTime<Utc>>,
231    pub model: Option<String>,
232    pub status: String,
233}
234
235/// One `ingest_log` row. `content_hash` is None for a row written before
236/// hashes became SHA-256, whose `file_hash` may then be the old 16-hex form.
237#[derive(Debug, Clone, PartialEq, Eq)]
238pub struct IngestLogEntry {
239    pub file_path: String,
240    pub file_hash: String,
241    pub content_hash: Option<String>,
242    pub session_key: Option<String>,
243    /// Ingested before raw ids became deterministic.
244    pub legacy_ids: bool,
245}
246
247/// What ingest records for a file it parsed or skipped. `legacy_ids` can
248/// only set the flag on a row, never clear it.
249#[derive(Debug, Clone, Copy)]
250pub struct IngestRecord<'a> {
251    pub file_path: &'a str,
252    /// SHA-256 of the file, lowercase hex.
253    pub content_hash: &'a str,
254    pub session_key: Option<&'a str>,
255    pub legacy_ids: bool,
256    pub memory_count: usize,
257    pub source: &'a str,
258}
259
260#[derive(Debug, Clone, Serialize, Deserialize)]
261pub struct SyncEntry {
262    pub id: String,
263    pub local_seq: i64,
264    pub origin_machine_id: String,
265    pub origin_seq: i64,
266    pub op: SyncOp,
267    pub node_type: SyncNodeType,
268    pub node_id: String,
269    pub timestamp: DateTime<Utc>,
270    pub data: Option<String>,
271}
272
273/// Wire form of a sync-log entry: same fields as SyncEntry but with `data`
274/// parsed to JSON. Lives in core so StoreAdmin::apply_record can take it
275/// without core depending on the sync crate.
276#[derive(Debug, Clone, Serialize, Deserialize)]
277pub struct SyncRecord {
278    pub local_seq: u64,
279    pub origin_machine_id: String,
280    pub origin_seq: u64,
281    pub op: SyncOp,
282    pub node_type: SyncNodeType,
283    pub node_id: String,
284    pub timestamp: DateTime<Utc>,
285    pub data: Option<serde_json::Value>,
286}
287
288#[derive(Debug, Clone, Serialize, Deserialize)]
289pub struct SyncState {
290    pub peer_id: String,
291    pub last_seq: u64,
292    pub last_sync_at: DateTime<Utc>,
293}
294
295#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
296pub struct CompactStats {
297    pub groups_with_duplicates: u64,
298    pub rows_deleted: u64,
299    pub max_local_seq_before: u64,
300    pub max_local_seq_after: u64,
301}