car_memgine/

note_store.rs

//! The on-disk note store behind CAR's durable memory.
//!
//! One JSON file — `<CAR_HOME>/memory/assistant.json` by default — holding a
//! flat `Vec<Note>`, re-ingested into a fresh [`MemgineEngine`] on load. This
//! is what makes "the assistant remembers across restarts" true.
//!
//! ## Why this lives in `car-memgine`
//!
//! It was private to `car-server-core`'s assistant, which is the only place
//! that could reach it — and `car-server-core` depends on `car-mcp`, not the
//! other way round, so the MCP server had no way to read or write the same
//! store. It therefore ran on a throwaway in-memory graph: facts a host wrote
//! over MCP vanished when stdin closed, and `memory_query` never saw anything
//! the user had actually remembered (car#972 §1).
//!
//! The fix needs one definition of the format reachable from both. Copying it
//! into `car-mcp` would have made two writers to one file agree only by
//! coincidence; here, a change to the format is a compile error in every
//! caller instead of a silent divergence in what one process reads and another
//! writes.
//!
//! ## Ids are positional, and that is load-bearing
//!
//! [`ingest`] derives a node id from the note's **index** in the file, so
//! reloading the same file reconstructs the same graph — nodes keep their
//! identity, and edges into them survive a restart. Two consequences worth
//! knowing before editing:
//!
//! - Notes must be appended, never reordered. Reordering silently re-points
//!   every id after the change.
//! - A writer that rebuilds the store from scratch must ingest in file order.
//!
//! ## Concurrency
//!
//! There is no lock. Callers mutate with [`load`] → modify → [`save`], which
//! narrows but does not close the window where two processes writing at once
//! lose one side's append. That is acceptable for the current writers (an
//! interactive assistant and an editor plugin, both driven by one human) and
//! is NOT acceptable for an automated fleet. Anything that needs stronger
//! guarantees should go through the daemon, which owns a single engine.

use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::proactive::ProactiveMemorySave;
use crate::MemgineEngine;

/// The model-facing memory taxonomy. Each variant routes to genuinely
/// different downstream behavior in memgine — this is the behavioral hint the
/// tool schema carries instead of prose in a system prompt telling the model
/// what is "worth keeping".
#[derive(Clone, Copy, Default, PartialEq, Eq, Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum NoteKind {
    /// Retrieved when relevant to the query (the Facts layer).
    #[default]
    Fact,
    /// A standing instruction. Saved as a memgine *constraint*, so it lands in
    /// the Active Constraints layer that context assembly includes in every
    /// session regardless of query.
    Preference,
    /// Procedural evidence — what was attempted and whether it worked.
    Procedure,
}

impl NoteKind {
    /// Strict parse for a value a model supplied. An unknown kind is an error
    /// the model can see and correct.
    pub fn parse(raw: Option<&str>) -> Result<Self, String> {
        match raw.map(str::trim) {
            None | Some("") | Some("fact") => Ok(Self::Fact),
            Some("preference") => Ok(Self::Preference),
            Some("procedure") => Ok(Self::Procedure),
            Some(other) => Err(format!(
                "unknown kind '{other}' (expected fact, preference, or procedure)"
            )),
        }
    }

    /// The wire spelling, matching the serde `rename_all = "lowercase"` and
    /// the vocabulary [`Self::parse`] accepts.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Fact => "fact",
            Self::Preference => "preference",
            Self::Procedure => "procedure",
        }
    }

    /// Lenient read-side parse for a value that came off the sync wire.
    ///
    /// Unlike [`Self::parse`], an unrecognized kind is NOT an error: it means
    /// a peer running a newer build used a variant this device does not know
    /// about, and degrading that to a plain fact is strictly better than
    /// dropping the fact or failing the recall.
    pub fn from_wire(raw: Option<&str>) -> Self {
        Self::parse(raw).unwrap_or_default()
    }

    /// Map the `constraint`/`pattern` vocabulary the MCP tool schema and the
    /// `memory.persist` wire format use onto this one.
    ///
    /// Those surfaces predate `NoteKind` and speak a different dialect: they
    /// carry a free-form `kind` where only the exact string `"constraint"`
    /// means anything, and everything else (including the documented default
    /// `"pattern"`) is a plain fact. Both dialects now write the SAME file, so
    /// the translation has to live somewhere explicit rather than being
    /// re-derived — a `"constraint"` that round-trips as a `Fact` silently
    /// demotes a standing rule to something recall only sometimes surfaces.
    pub fn from_constraint_dialect(raw: Option<&str>) -> Self {
        match raw.map(str::trim) {
            Some("constraint") => Self::Preference,
            Some("procedure") => Self::Procedure,
            _ => Self::Fact,
        }
    }

    /// Whether this note is a standing rule, and therefore a memgine
    /// constraint rather than a query-matched fact.
    pub fn is_constraint(self) -> bool {
        self == Self::Preference
    }
}

/// One remembered note, as stored on disk.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Note {
    pub subject: String,
    pub body: String,
    /// How the fact is used at recall time. `#[serde(default)]` so notes
    /// written before the field existed load as plain facts rather than
    /// failing the whole store's deserialization.
    #[serde(default)]
    pub kind: NoteKind,
}

/// Default durable-memory path: `memory/assistant.json` under the CAR state
/// root — `CAR_HOME` when set, otherwise `~/.car`, and a relative `.car` when
/// neither resolves.
pub fn default_path() -> PathBuf {
    car_home::root_or_relative()
        .join("memory")
        .join("assistant.json")
}

/// Read the store, or an empty set if it is missing or unreadable.
///
/// Deliberately lenient. A missing file is the first run. A corrupt file is a
/// bad outcome either way, and refusing to start is worse than starting empty
/// — the alternative is an assistant that cannot run at all because one note
/// was truncated by a crash mid-write.
///
/// The cost of that leniency is real and worth stating: a corrupt store reads
/// as "no memories", and the next [`save`] overwrites it. Callers that can
/// afford to should distinguish the two with [`load_checked`].
pub fn load(path: &Path) -> Vec<Note> {
    load_checked(path).unwrap_or_default()
}

/// Read the store, distinguishing "absent" from "present but unreadable".
///
/// `Ok(vec![])` means there is no store yet. `Err` means one exists and could
/// not be parsed — a caller about to overwrite it should say so rather than
/// silently discarding whatever it held.
pub fn load_checked(path: &Path) -> Result<Vec<Note>, String> {
    let raw = match std::fs::read_to_string(path) {
        Ok(raw) => raw,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(e) => return Err(format!("read {}: {e}", path.display())),
    };
    serde_json::from_str(&raw).map_err(|e| format!("parse {}: {e}", path.display()))
}

/// Write the store, creating the parent directory if needed.
///
/// Writes the whole set rather than appending: the file is small, and
/// correctness beats cleverness on the store that holds the user's memory.
pub fn save(path: &Path, notes: &[Note]) -> Result<(), String> {
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent).map_err(|e| format!("create {}: {e}", parent.display()))?;
    }
    let serialized = serde_json::to_string_pretty(notes).map_err(|e| format!("serialize: {e}"))?;
    std::fs::write(path, serialized).map_err(|e| format!("write {}: {e}", path.display()))
}

/// Ingest one note as a memgine fact.
///
/// The id is derived from `idx` so a reload re-creates the same graph — see
/// the module docs on why notes must be appended rather than reordered.
pub fn ingest(engine: &mut MemgineEngine, idx: usize, note: &Note) {
    let save = ProactiveMemorySave {
        id: Some(format!("assistant-note-{idx}")),
        subject: note.subject.clone(),
        body: note.body.clone(),
        tags: vec!["assistant_memory".to_string()],
        confidence: Some("high".to_string()),
        tenant_id: None,
        // A preference is a standing rule: mark it a constraint so context
        // assembly surfaces it in the always-included Active Constraints layer
        // rather than only when the query happens to match.
        is_constraint: note.kind.is_constraint(),
    };
    match note.kind {
        NoteKind::Procedure => engine.save_proactive_procedural(save),
        NoteKind::Fact | NoteKind::Preference => engine.save_proactive_knowledge(save),
    };
}

/// Ingest a whole store, in file order.
pub fn ingest_all(engine: &mut MemgineEngine, notes: &[Note]) {
    for (idx, note) in notes.iter().enumerate() {
        ingest(engine, idx, note);
    }
}

/// Build a fresh engine holding exactly the notes at `path`.
pub fn engine_from(path: &Path) -> (MemgineEngine, Vec<Note>) {
    let notes = load(path);
    let mut engine = MemgineEngine::new(None);
    ingest_all(&mut engine, &notes);
    (engine, notes)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn note(subject: &str, kind: NoteKind) -> Note {
        Note {
            subject: subject.into(),
            body: "body".into(),
            kind,
        }
    }

    #[test]
    fn a_missing_store_is_the_first_run_not_an_error() {
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("nope.json");
        assert_eq!(load_checked(&p), Ok(Vec::new()));
        assert!(load(&p).is_empty());
    }

    #[test]
    fn a_corrupt_store_is_distinguishable_from_an_empty_one() {
        // `load` degrades to empty so the assistant can still start; the whole
        // point of `load_checked` is that a caller about to overwrite the file
        // can tell it held something first.
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("bad.json");
        std::fs::write(&p, "{ not json").unwrap();
        assert!(load(&p).is_empty());
        assert!(load_checked(&p).is_err());
    }

    #[test]
    fn notes_round_trip_through_the_file() {
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("memory.json");
        let notes = vec![
            note("pet", NoteKind::Fact),
            note("always use tabs", NoteKind::Preference),
            note("deploy runbook", NoteKind::Procedure),
        ];
        save(&p, &notes).unwrap();
        assert_eq!(load(&p), notes);
    }

    #[test]
    fn save_creates_the_parent_directory() {
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("nested").join("deeper").join("memory.json");
        save(&p, &[note("x", NoteKind::Fact)]).unwrap();
        assert_eq!(load(&p).len(), 1);
    }

    #[test]
    fn a_note_written_before_kind_existed_loads_as_a_fact() {
        let dir = tempfile::tempdir().unwrap();
        let p = dir.path().join("legacy.json");
        std::fs::write(&p, r#"[{"subject":"s","body":"b"}]"#).unwrap();
        assert_eq!(load(&p)[0].kind, NoteKind::Fact);
    }

    #[test]
    fn the_constraint_dialect_maps_onto_the_note_taxonomy() {
        // The bug this prevents: an MCP client writes kind "constraint", it
        // round-trips as a plain Fact, and a standing rule silently stops
        // appearing in the always-included constraints layer.
        assert_eq!(
            NoteKind::from_constraint_dialect(Some("constraint")),
            NoteKind::Preference
        );
        assert!(NoteKind::from_constraint_dialect(Some("constraint")).is_constraint());
        // "pattern" is the documented default of that dialect, and is a fact.
        assert_eq!(
            NoteKind::from_constraint_dialect(Some("pattern")),
            NoteKind::Fact
        );
        assert_eq!(NoteKind::from_constraint_dialect(None), NoteKind::Fact);
        assert_eq!(
            NoteKind::from_constraint_dialect(Some("procedure")),
            NoteKind::Procedure
        );
    }

    #[test]
    fn strict_parse_rejects_what_lenient_parse_degrades() {
        assert!(NoteKind::parse(Some("nonsense")).is_err());
        assert_eq!(NoteKind::from_wire(Some("nonsense")), NoteKind::Fact);
    }

    #[test]
    fn reloading_a_store_reconstructs_the_same_node_ids() {
        // Positional ids are what let edges into a remembered fact survive a
        // restart. If this breaks, memory still "works" and the graph quietly
        // stops being a graph.
        let notes = vec![note("a", NoteKind::Fact), note("b", NoteKind::Preference)];
        let ids = |notes: &[Note]| {
            let mut e = MemgineEngine::new(None);
            ingest_all(&mut e, notes);
            let mut got: Vec<String> = e
                .graph
                .inner
                .node_indices()
                .filter_map(|i| e.graph.inner.node_weight(i))
                .filter_map(|n| n.fact_id.clone())
                .collect();
            got.sort();
            got
        };
        let first = ids(&notes);
        assert!(!first.is_empty(), "ingest produced no fact nodes");
        assert_eq!(first, ids(&notes));
    }
}