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/// The source of a note an agent writes about its own session.
23pub const AGENT_NOTE_SOURCE: &str = "agent-note";
24
25/// Sources written through `remember` (over MCP, the HTTP API default,
26/// `sb remember`, the ask service and its autonomous trigger), from
27/// Claude's own memory files and markdown vaults, or as agent notes, rather
28/// than mined from a transcript.
29/// Consolidation must leave these alone: a paraphrase of an explicit note
30/// loses exactly the wording its author chose.
31pub const EXPLICIT_SOURCES: &[&str] = &[
32    "mcp-direct",
33    "api",
34    "cli",
35    "ask",
36    "ask-auto",
37    "claude-memory",
38    AGENT_NOTE_SOURCE,
39    "markdown",
40];
41
42/// Sources read from documents the user wrote in their repositories: commit
43/// messages, pull request bodies and agent instruction files. Consolidation
44/// leaves these alone too, because a newer version supersedes the raw it
45/// replaces and a distillate of the old wording would outlive it.
46pub const DOCUMENT_SOURCES: &[&str] = &["git-commit", "git-pr", "repo-instructions"];
47
48/// SQL fragment over `$col` admitting only sources consolidation may
49/// distill: neither distillates themselves nor the explicit or document
50/// sources. The literals must list exactly `EXPLICIT_SOURCES` and
51/// `DOCUMENT_SOURCES`; a test enforces it.
52macro_rules! explicit_sources_list {
53    () => {
54        "'mcp-direct', 'api', 'cli', 'ask', 'ask-auto', 'claude-memory', 'agent-note', 'markdown'"
55    };
56}
57macro_rules! document_sources_list {
58    () => {
59        "'git-commit', 'git-pr', 'repo-instructions'"
60    };
61}
62macro_rules! distillable_source {
63    ($col:literal) => {
64        concat!(
65            $col,
66            " NOT IN ('consolidation', ",
67            $crate::schema::explicit_sources_list!(),
68            ", ",
69            $crate::schema::document_sources_list!(),
70            ")"
71        )
72    };
73}
74pub(crate) use {distillable_source, document_sources_list, explicit_sources_list};
75
76#[derive(Debug, Clone, Serialize, Deserialize)]
77pub struct Memory {
78    pub id: Uuid,
79    pub content: String,
80    pub embedding: Vec<f32>,
81    pub memory_type: MemoryType,
82    pub confidence: f32,
83    pub created_at: DateTime<Utc>,
84    pub last_accessed: DateTime<Utc>,
85    pub access_count: u32,
86    pub source: String,
87    pub source_id: String,
88    #[serde(default)]
89    pub project_path: Option<String>,
90    #[serde(default)]
91    pub machine_id: String,
92    #[serde(default = "epoch")]
93    pub updated_at: DateTime<Utc>,
94    /// LLM-generated chunk context for contextual retrieval; indexed and
95    /// embedded together with `content`, backfilled nightly.
96    #[serde(default)]
97    pub context: Option<String>,
98    #[serde(default)]
99    pub conversation_id: Option<Uuid>,
100    #[serde(default)]
101    pub tier: Tier,
102    /// Cold-tier segment id once archived; content is then a stub and the
103    /// embedding is dropped from the row.
104    #[serde(default)]
105    pub archived_segment: Option<String>,
106    /// Zep-style soft invalidation: a superseded memory stays in the store
107    /// but leaves the retrieval indexes.
108    #[serde(default)]
109    pub superseded_by: Option<Uuid>,
110    /// Set when `forget` retired the memory: it is archived like a
111    /// consolidated raw but must never be restored with them.
112    #[serde(default)]
113    pub retired_reason: Option<String>,
114    /// When the session this knowledge came from happened: the transcript
115    /// line's time, or for a distillate the latest of its raws. None means
116    /// no evidence survives, which must be shown as unknown, never guessed
117    /// from `created_at` (that is the ingest or distill time).
118    #[serde(default)]
119    pub session_at: Option<DateTime<Utc>>,
120}
121
122#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
123#[serde(rename_all = "snake_case")]
124pub enum Tier {
125    #[default]
126    Hot,
127    Archived,
128}
129
130#[derive(Debug, Clone, Serialize, Deserialize)]
131pub struct Entity {
132    pub id: Uuid,
133    pub name: String,
134    pub entity_type: String,
135    pub embedding: Vec<f32>,
136    pub aliases: Vec<String>,
137}
138
139#[derive(Debug, Clone, Serialize, Deserialize)]
140pub struct Conversation {
141    pub id: Uuid,
142    pub source: String,
143    pub machine_id: String,
144    pub started_at: DateTime<Utc>,
145    pub project_path: Option<String>,
146}
147
148impl Conversation {
149    /// Stable across stores and machines, so the same Claude Code session
150    /// ingested twice lands on one conversation row, and a note filed under
151    /// the session's id finds it.
152    pub fn claude_code_id(session_key: &str) -> Uuid {
153        Uuid::new_v5(
154            &Uuid::NAMESPACE_OID,
155            format!("claude-code:{session_key}").as_bytes(),
156        )
157    }
158}
159
160#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
161#[serde(rename_all = "snake_case")]
162pub enum RelationType {
163    RelatesTo,
164    Mentions,
165    DerivedFrom,
166    Contradicts,
167    Reinforces,
168    Supersedes,
169    DistilledFrom,
170}
171
172#[derive(Debug, Clone, Serialize, Deserialize)]
173pub struct Relation {
174    pub from_id: Uuid,
175    pub to_id: Uuid,
176    pub relation_type: RelationType,
177    pub strength: f32,
178    pub context: Option<String>,
179}
180
181impl Memory {
182    pub fn new(
183        content: String,
184        memory_type: MemoryType,
185        source: String,
186        source_id: String,
187    ) -> Self {
188        let now = Utc::now();
189        Self {
190            id: Uuid::new_v4(),
191            content,
192            embedding: Vec::new(),
193            memory_type,
194            confidence: 1.0,
195            created_at: now,
196            last_accessed: now,
197            access_count: 0,
198            source,
199            source_id,
200            project_path: None,
201            machine_id: String::new(),
202            updated_at: now,
203            context: None,
204            conversation_id: None,
205            tier: Tier::Hot,
206            archived_segment: None,
207            superseded_by: None,
208            retired_reason: None,
209            session_at: None,
210        }
211    }
212
213    pub fn with_project_path(mut self, path: Option<String>) -> Self {
214        self.project_path = path;
215        self
216    }
217
218    pub fn with_machine_id(mut self, machine_id: String) -> Self {
219        self.machine_id = machine_id;
220        self
221    }
222}
223
224impl Entity {
225    pub fn new(name: String, entity_type: String) -> Self {
226        Self {
227            id: Uuid::new_v4(),
228            name,
229            entity_type,
230            embedding: Vec::new(),
231            aliases: Vec::new(),
232        }
233    }
234}
235
236#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
237#[serde(rename_all = "snake_case")]
238pub enum SyncOp {
239    Create,
240    Update,
241    Delete,
242}
243
244#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
245#[serde(rename_all = "snake_case")]
246pub enum SyncNodeType {
247    Memory,
248    Entity,
249    Conversation,
250    Relation,
251    Distillation,
252}
253
254/// The record that a memory has already been distilled. Without this on the
255/// wire only the distilled Memory replicates, never the fact that the source
256/// was consumed, so every peer re-distills the same memories against the same
257/// shared GPU.
258#[derive(Debug, Clone, Serialize, Deserialize)]
259pub struct Distillation {
260    pub memory_id: Uuid,
261    pub distilled_id: Option<Uuid>,
262    pub distilled_at: Option<DateTime<Utc>>,
263    pub model: Option<String>,
264    pub status: String,
265}
266
267/// One `ingest_log` row. `content_hash` is None for a row written before
268/// hashes became SHA-256, whose `file_hash` may then be the old 16-hex form.
269#[derive(Debug, Clone, PartialEq, Eq)]
270pub struct IngestLogEntry {
271    pub file_path: String,
272    pub file_hash: String,
273    pub content_hash: Option<String>,
274    pub session_key: Option<String>,
275    /// Ingested before raw ids became deterministic.
276    pub legacy_ids: bool,
277}
278
279/// What ingest records for a file it parsed or skipped. `legacy_ids` can
280/// only set the flag on a row, never clear it.
281#[derive(Debug, Clone, Copy)]
282pub struct IngestRecord<'a> {
283    pub file_path: &'a str,
284    /// SHA-256 of the file, lowercase hex.
285    pub content_hash: &'a str,
286    pub session_key: Option<&'a str>,
287    pub legacy_ids: bool,
288    pub memory_count: usize,
289    pub source: &'a str,
290}
291
292#[derive(Debug, Clone, Serialize, Deserialize)]
293pub struct SyncEntry {
294    pub id: String,
295    pub local_seq: i64,
296    pub origin_machine_id: String,
297    pub origin_seq: i64,
298    pub op: SyncOp,
299    pub node_type: SyncNodeType,
300    pub node_id: String,
301    pub timestamp: DateTime<Utc>,
302    pub data: Option<String>,
303}
304
305/// Wire form of a sync-log entry: same fields as SyncEntry but with `data`
306/// parsed to JSON. Lives in core so StoreAdmin::apply_record can take it
307/// without core depending on the sync crate.
308#[derive(Debug, Clone, Serialize, Deserialize)]
309pub struct SyncRecord {
310    pub local_seq: u64,
311    pub origin_machine_id: String,
312    pub origin_seq: u64,
313    pub op: SyncOp,
314    pub node_type: SyncNodeType,
315    pub node_id: String,
316    pub timestamp: DateTime<Utc>,
317    pub data: Option<serde_json::Value>,
318}
319
320#[derive(Debug, Clone, Serialize, Deserialize)]
321pub struct SyncState {
322    pub peer_id: String,
323    pub last_seq: u64,
324    pub last_sync_at: DateTime<Utc>,
325}
326
327#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
328pub struct CompactStats {
329    pub groups_with_duplicates: u64,
330    pub rows_deleted: u64,
331    pub max_local_seq_before: u64,
332    pub max_local_seq_after: u64,
333}
334
335#[cfg(test)]
336mod tests {
337    use super::*;
338
339    #[test]
340    fn agent_notes_are_explicit_so_consolidation_leaves_them_alone() {
341        assert_eq!(AGENT_NOTE_SOURCE, "agent-note");
342        assert!(EXPLICIT_SOURCES.contains(&AGENT_NOTE_SOURCE));
343        assert!(distillable_source!("source").contains("'agent-note'"));
344    }
345}