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    /// Who wrote the memory: the writer's user id, or when the writer named
121    /// none this store's identity tag, `device:<machine id>` before it has
122    /// one. None only on rows from before authors were recorded. Never
123    /// changes once the row exists.
124    #[serde(default)]
125    pub author: Option<String>,
126    #[serde(default)]
127    pub scope: Scope,
128}
129
130/// Who may read a memory besides its author. Private memories reach only
131/// their author; shared ones every user of the same store (a kiln tenant).
132#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
133#[serde(rename_all = "snake_case")]
134pub enum Scope {
135    #[default]
136    Private,
137    Shared,
138}
139
140#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
141#[serde(rename_all = "snake_case")]
142pub enum Tier {
143    #[default]
144    Hot,
145    Archived,
146}
147
148#[derive(Debug, Clone, Serialize, Deserialize)]
149pub struct Entity {
150    pub id: Uuid,
151    pub name: String,
152    pub entity_type: String,
153    pub embedding: Vec<f32>,
154    pub aliases: Vec<String>,
155}
156
157#[derive(Debug, Clone, Serialize, Deserialize)]
158pub struct Conversation {
159    pub id: Uuid,
160    pub source: String,
161    pub machine_id: String,
162    pub started_at: DateTime<Utc>,
163    pub project_path: Option<String>,
164}
165
166impl Conversation {
167    /// Stable across stores and machines, so the same Claude Code session
168    /// ingested twice lands on one conversation row, and a note filed under
169    /// the session's id finds it.
170    pub fn claude_code_id(session_key: &str) -> Uuid {
171        Uuid::new_v5(
172            &Uuid::NAMESPACE_OID,
173            format!("claude-code:{session_key}").as_bytes(),
174        )
175    }
176}
177
178#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
179#[serde(rename_all = "snake_case")]
180pub enum RelationType {
181    RelatesTo,
182    Mentions,
183    DerivedFrom,
184    Contradicts,
185    Reinforces,
186    Supersedes,
187    DistilledFrom,
188}
189
190#[derive(Debug, Clone, Serialize, Deserialize)]
191pub struct Relation {
192    pub from_id: Uuid,
193    pub to_id: Uuid,
194    pub relation_type: RelationType,
195    pub strength: f32,
196    pub context: Option<String>,
197}
198
199impl Memory {
200    pub fn new(
201        content: String,
202        memory_type: MemoryType,
203        source: String,
204        source_id: String,
205    ) -> Self {
206        let now = Utc::now();
207        Self {
208            id: Uuid::new_v4(),
209            content,
210            embedding: Vec::new(),
211            memory_type,
212            confidence: 1.0,
213            created_at: now,
214            last_accessed: now,
215            access_count: 0,
216            source,
217            source_id,
218            project_path: None,
219            machine_id: String::new(),
220            updated_at: now,
221            context: None,
222            conversation_id: None,
223            tier: Tier::Hot,
224            archived_segment: None,
225            superseded_by: None,
226            retired_reason: None,
227            session_at: None,
228            author: None,
229            scope: Scope::Private,
230        }
231    }
232
233    pub fn with_project_path(mut self, path: Option<String>) -> Self {
234        self.project_path = path;
235        self
236    }
237
238    pub fn with_machine_id(mut self, machine_id: String) -> Self {
239        self.machine_id = machine_id;
240        self
241    }
242}
243
244impl Entity {
245    pub fn new(name: String, entity_type: String) -> Self {
246        Self {
247            id: Uuid::new_v4(),
248            name,
249            entity_type,
250            embedding: Vec::new(),
251            aliases: Vec::new(),
252        }
253    }
254}
255
256#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
257#[serde(rename_all = "snake_case")]
258pub enum SyncOp {
259    Create,
260    Update,
261    Delete,
262}
263
264#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
265#[serde(rename_all = "snake_case")]
266pub enum SyncNodeType {
267    Memory,
268    Entity,
269    Conversation,
270    Relation,
271    Distillation,
272}
273
274/// The record that a memory has already been distilled. Without this on the
275/// wire only the distilled Memory replicates, never the fact that the source
276/// was consumed, so every peer re-distills the same memories against the same
277/// shared GPU.
278#[derive(Debug, Clone, Serialize, Deserialize)]
279pub struct Distillation {
280    pub memory_id: Uuid,
281    pub distilled_id: Option<Uuid>,
282    pub distilled_at: Option<DateTime<Utc>>,
283    pub model: Option<String>,
284    pub status: String,
285}
286
287/// One `ingest_log` row. `content_hash` is None for a row written before
288/// hashes became SHA-256, whose `file_hash` may then be the old 16-hex form.
289#[derive(Debug, Clone, PartialEq, Eq)]
290pub struct IngestLogEntry {
291    pub file_path: String,
292    pub file_hash: String,
293    pub content_hash: Option<String>,
294    pub session_key: Option<String>,
295    /// Ingested before raw ids became deterministic.
296    pub legacy_ids: bool,
297}
298
299/// What ingest records for a file it parsed or skipped. `legacy_ids` can
300/// only set the flag on a row, never clear it.
301#[derive(Debug, Clone, Copy)]
302pub struct IngestRecord<'a> {
303    pub file_path: &'a str,
304    /// SHA-256 of the file, lowercase hex.
305    pub content_hash: &'a str,
306    pub session_key: Option<&'a str>,
307    pub legacy_ids: bool,
308    pub memory_count: usize,
309    pub source: &'a str,
310}
311
312#[derive(Debug, Clone, Serialize, Deserialize)]
313pub struct SyncEntry {
314    pub id: String,
315    pub local_seq: i64,
316    pub origin_machine_id: String,
317    pub origin_seq: i64,
318    pub op: SyncOp,
319    pub node_type: SyncNodeType,
320    pub node_id: String,
321    pub timestamp: DateTime<Utc>,
322    pub data: Option<String>,
323}
324
325/// Wire form of a sync-log entry: same fields as SyncEntry but with `data`
326/// parsed to JSON. Lives in core so StoreAdmin::apply_record can take it
327/// without core depending on the sync crate.
328#[derive(Debug, Clone, Serialize, Deserialize)]
329pub struct SyncRecord {
330    pub local_seq: u64,
331    pub origin_machine_id: String,
332    pub origin_seq: u64,
333    pub op: SyncOp,
334    pub node_type: SyncNodeType,
335    pub node_id: String,
336    pub timestamp: DateTime<Utc>,
337    pub data: Option<serde_json::Value>,
338}
339
340#[derive(Debug, Clone, Serialize, Deserialize)]
341pub struct SyncState {
342    pub peer_id: String,
343    pub last_seq: u64,
344    pub last_sync_at: DateTime<Utc>,
345}
346
347#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
348pub struct CompactStats {
349    pub groups_with_duplicates: u64,
350    pub rows_deleted: u64,
351    pub max_local_seq_before: u64,
352    pub max_local_seq_after: u64,
353}
354
355#[cfg(test)]
356mod tests {
357    use super::*;
358
359    #[test]
360    fn agent_notes_are_explicit_so_consolidation_leaves_them_alone() {
361        assert_eq!(AGENT_NOTE_SOURCE, "agent-note");
362        assert!(EXPLICIT_SOURCES.contains(&AGENT_NOTE_SOURCE));
363        assert!(distillable_source!("source").contains("'agent-note'"));
364    }
365}