handoff-mcp-server 0.11.0 → 0.13.0

package/src/storage/memory/injected.rs

@@ -0,0 +1,340 @@
+//! Per-session "already injected" sidecars under `.handoff/memory/injected/`.
+//!
+//! ```text
+//! .handoff/memory/injected/
+//!   <hook_session_id>.json   # { session_id, updated_at, injected: { id -> hash } }
+//! ```
+//!
+//! The sidecar is keyed by the **hook's `session_id`** (not the timestamped
+//! session file): the hook never sees a session filename, and the id is stable
+//! across compaction/resume but changes on `/clear` — which gives us a free
+//! per-conversation reset.
+//!
+//! A memory's value is its `content_hash`. `memory_query` skips a memory whose
+//! id is present with the *same* hash (already injected this session) but
+//! re-injects when the hash differs (the memory was edited since). All writes go
+//! through [`crate::storage::atomic_write`] so a concurrent reader never sees a
+//! torn file; reads are lenient (a corrupt sidecar is treated as empty).
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+
+use super::memory_dir;
+
+/// Current sidecar schema version.
+pub const INJECTED_SCHEMA_VERSION: u32 = 1;
+
+/// The set of memories already injected into one hook session.
+///
+/// `injected` maps memory id → the `content_hash` that was injected, so an edited
+/// memory (new hash) is re-injected while an unchanged one is skipped.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InjectedSet {
+    /// Schema version (= [`INJECTED_SCHEMA_VERSION`]).
+    #[serde(default = "default_version")]
+    pub version: u32,
+    /// The hook session id this sidecar belongs to.
+    pub session_id: String,
+    /// RFC3339 timestamp of the last update.
+    pub updated_at: String,
+    /// memory id → injected `content_hash`.
+    #[serde(default)]
+    pub injected: BTreeMap<String, String>,
+}
+
+fn default_version() -> u32 {
+    INJECTED_SCHEMA_VERSION
+}
+
+impl InjectedSet {
+    /// A fresh, empty set for `session_id`.
+    pub fn new(session_id: String, now: String) -> Self {
+        InjectedSet {
+            version: INJECTED_SCHEMA_VERSION,
+            session_id,
+            updated_at: now,
+            injected: BTreeMap::new(),
+        }
+    }
+
+    /// True if `id` was already injected this session with the *same* hash. A
+    /// differing hash (edited memory) returns false so it is re-injected.
+    pub fn already_injected(&self, id: &str, content_hash: &str) -> bool {
+        self.injected.get(id).map(String::as_str) == Some(content_hash)
+    }
+
+    /// Record `id`→`content_hash` as injected. Returns true if this changed the
+    /// set (new id or a different hash), false if it was already present.
+    pub fn mark(&mut self, id: &str, content_hash: &str) -> bool {
+        match self.injected.get(id) {
+            Some(existing) if existing == content_hash => false,
+            _ => {
+                self.injected
+                    .insert(id.to_string(), content_hash.to_string());
+                true
+            }
+        }
+    }
+}
+
+/// Path to the `injected/` directory inside a `memory/` dir.
+pub fn injected_dir(handoff_dir: &Path) -> PathBuf {
+    memory_dir(handoff_dir).join("injected")
+}
+
+/// Sanitize a hook session id into a safe, **collision-free** single-path
+/// file stem.
+///
+/// Session ids are opaque strings from the hook environment; we must never let
+/// one escape `injected/` (path traversal) or collide with the temp-file naming
+/// in `atomic_write`. Two requirements:
+///
+/// 1. **Safety**: the stem is a single path component — no `/`, `\`, `..`, or
+///    leading `.` can survive (each unsafe char becomes `_`, leading dots are
+///    dropped).
+/// 2. **Uniqueness**: the readable part alone is lossy (`a/b` and `a_b` would
+///    map to the same `a_b`), so we always append `-<fnv1a(raw id)>`. Distinct
+///    raw ids therefore never share a sidecar, while the stem stays
+///    human-recognizable. The hash is over the *raw* id, so it disambiguates
+///    even when the readable prefix is identical or empty.
+fn sanitize_session_id(session_id: &str) -> String {
+    let mut out = String::with_capacity(session_id.len());
+    for ch in session_id.chars() {
+        if ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-') {
+            out.push(ch);
+        } else if ch == '.' {
+            // Keep dots only when not leading (avoid hidden files / `..`).
+            if !out.is_empty() {
+                out.push('.');
+            }
+        } else {
+            out.push('_');
+        }
+    }
+    // Trim trailing dots so we never produce `name.`, and cap the readable part.
+    let trimmed = out.trim_end_matches('.');
+    let prefix: String = trimmed.chars().take(96).collect();
+    let prefix = if prefix.is_empty() { "anon" } else { &prefix };
+    // Always disambiguate with a hash of the RAW id (std-only FNV-1a).
+    format!("{prefix}-{}", lexsim::fnv1a_hex(session_id.as_bytes()))
+}
+
+/// Path to one session's sidecar file.
+pub fn injected_path(handoff_dir: &Path, session_id: &str) -> PathBuf {
+    injected_dir(handoff_dir).join(format!("{}.json", sanitize_session_id(session_id)))
+}
+
+/// Read the injected set for `session_id`. Returns a fresh empty set when the
+/// file does not exist or is unparseable (lenient: a corrupt sidecar must not
+/// break injection — at worst a memory is shown twice).
+pub fn read_injected_set(handoff_dir: &Path, session_id: &str, now: &str) -> InjectedSet {
+    let path = injected_path(handoff_dir, session_id);
+    match std::fs::read_to_string(&path) {
+        Ok(content) => serde_json::from_str::<InjectedSet>(&content)
+            .unwrap_or_else(|_| InjectedSet::new(session_id.to_string(), now.to_string())),
+        Err(_) => InjectedSet::new(session_id.to_string(), now.to_string()),
+    }
+}
+
+/// Write a session's injected set atomically, creating `injected/` lazily.
+pub fn write_injected_set(handoff_dir: &Path, set: &InjectedSet) -> Result<PathBuf> {
+    let dir = injected_dir(handoff_dir);
+    std::fs::create_dir_all(&dir)
+        .with_context(|| format!("Failed to create injected dir: {}", dir.display()))?;
+    let path = injected_path(handoff_dir, &set.session_id);
+    let content = serde_json::to_string_pretty(set).context("Failed to serialize injected set")?;
+    crate::storage::atomic_write(&path, content.as_bytes())
+        .with_context(|| format!("Failed to write injected set: {}", path.display()))?;
+    Ok(path)
+}
+
+/// Garbage-collect sidecars whose `updated_at` is older than `max_age_days`.
+/// Returns the number of files removed. A sidecar with an unparseable
+/// `updated_at` is left alone (we can't tell its age). `now` is supplied so the
+/// caller controls the clock (testable).
+pub fn gc_injected_sets(
+    handoff_dir: &Path,
+    max_age_days: i64,
+    now: chrono::DateTime<chrono::Utc>,
+) -> Result<usize> {
+    let dir = injected_dir(handoff_dir);
+    if !dir.exists() {
+        return Ok(0);
+    }
+    let cutoff = now - chrono::Duration::days(max_age_days);
+    let mut removed = 0usize;
+    for entry in std::fs::read_dir(&dir)
+        .with_context(|| format!("Failed to read injected dir: {}", dir.display()))?
+        .filter_map(|e| e.ok())
+    {
+        let path = entry.path();
+        if !path.is_file() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.ends_with(".json") || name.starts_with('.') {
+            continue;
+        }
+        let Ok(content) = std::fs::read_to_string(&path) else {
+            continue;
+        };
+        let Ok(set) = serde_json::from_str::<InjectedSet>(&content) else {
+            continue; // unparseable → leave it (can't determine age)
+        };
+        let Ok(updated) = chrono::DateTime::parse_from_rfc3339(&set.updated_at) else {
+            continue; // bad timestamp → leave it
+        };
+        if updated.with_timezone(&chrono::Utc) < cutoff && std::fs::remove_file(&path).is_ok() {
+            removed += 1;
+        }
+    }
+    Ok(removed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn handoff(tmp: &TempDir) -> PathBuf {
+        let dir = tmp.path().join(".handoff");
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn read_missing_is_empty() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        let set = read_injected_set(&h, "sess-1", "2026-06-27T00:00:00Z");
+        assert_eq!(set.session_id, "sess-1");
+        assert!(set.injected.is_empty());
+    }
+
+    #[test]
+    fn write_then_read_roundtrip() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        let mut set = InjectedSet::new("sess-1".to_string(), "2026-06-27T00:00:00Z".to_string());
+        assert!(set.mark("m-1", "hashA"));
+        write_injected_set(&h, &set).unwrap();
+
+        let back = read_injected_set(&h, "sess-1", "now");
+        assert_eq!(back.injected.get("m-1").map(String::as_str), Some("hashA"));
+    }
+
+    #[test]
+    fn already_injected_same_hash_true_diff_hash_false() {
+        let mut set = InjectedSet::new("s".to_string(), "now".to_string());
+        set.mark("m-1", "hashA");
+        assert!(set.already_injected("m-1", "hashA"));
+        assert!(!set.already_injected("m-1", "hashB")); // edited → re-inject
+        assert!(!set.already_injected("m-2", "hashA")); // never injected
+    }
+
+    #[test]
+    fn mark_reports_change() {
+        let mut set = InjectedSet::new("s".to_string(), "now".to_string());
+        assert!(set.mark("m-1", "h1")); // new id
+        assert!(!set.mark("m-1", "h1")); // unchanged
+        assert!(set.mark("m-1", "h2")); // hash changed
+    }
+
+    #[test]
+    fn sessions_are_isolated() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        let mut a = InjectedSet::new("A".to_string(), "now".to_string());
+        a.mark("m-1", "h");
+        write_injected_set(&h, &a).unwrap();
+
+        let b = read_injected_set(&h, "B", "now");
+        assert!(
+            b.injected.is_empty(),
+            "session B must not see session A's set"
+        );
+    }
+
+    #[test]
+    fn sanitize_blocks_traversal_and_separators() {
+        // Path separators are neutralized so the result is always a single flat
+        // filename component — no traversal possible.
+        for evil in [
+            "../../etc/passwd",
+            "a/b\\c",
+            "..",
+            "../",
+            "foo/../bar",
+            ".hidden",
+            "",
+            "...",
+        ] {
+            let s = sanitize_session_id(evil);
+            assert!(!s.contains('/'), "{evil:?} -> {s:?} still has /");
+            assert!(!s.contains('\\'), "{evil:?} -> {s:?} still has \\");
+            assert_ne!(s, "..", "{evil:?} -> {s:?} is parent ref");
+            assert!(!s.starts_with('.'), "{evil:?} -> {s:?} is hidden");
+            assert!(!s.is_empty(), "{evil:?} -> empty stem");
+        }
+        // The readable prefix is preserved; a hash suffix is always appended.
+        assert!(sanitize_session_id("3f9a-1b2c-4d5e").starts_with("3f9a-1b2c-4d5e-"));
+        assert!(sanitize_session_id(".hidden").starts_with("hidden-"));
+    }
+
+    #[test]
+    fn sanitize_is_collision_free_for_distinct_ids() {
+        // Lossy normalization alone would collide these; the raw-id hash suffix
+        // keeps every distinct id on its own sidecar.
+        let pairs = [("a/b", "a_b"), ("...", ""), ("a.b", "a_b"), ("X/Y", "X.Y")];
+        for (x, y) in pairs {
+            assert_ne!(
+                sanitize_session_id(x),
+                sanitize_session_id(y),
+                "{x:?} and {y:?} must not share a sidecar"
+            );
+        }
+        // Same id is stable (round-trips to the same file).
+        assert_eq!(sanitize_session_id("sess-A"), sanitize_session_id("sess-A"));
+    }
+
+    #[test]
+    fn lenient_read_treats_corrupt_as_empty() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        let dir = injected_dir(&h);
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(injected_path(&h, "sess-1"), b"{not json").unwrap();
+
+        let set = read_injected_set(&h, "sess-1", "now");
+        assert!(set.injected.is_empty());
+    }
+
+    #[test]
+    fn gc_removes_old_keeps_fresh() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        let old = InjectedSet::new("old".to_string(), "2026-01-01T00:00:00Z".to_string());
+        let fresh = InjectedSet::new("fresh".to_string(), "2026-06-27T00:00:00Z".to_string());
+        write_injected_set(&h, &old).unwrap();
+        write_injected_set(&h, &fresh).unwrap();
+
+        let now = chrono::DateTime::parse_from_rfc3339("2026-06-28T00:00:00Z")
+            .unwrap()
+            .with_timezone(&chrono::Utc);
+        let removed = gc_injected_sets(&h, 14, now).unwrap();
+        assert_eq!(removed, 1, "only the January sidecar is past 14 days");
+        assert!(read_injected_set(&h, "old", "now").injected.is_empty());
+        assert!(injected_path(&h, "fresh").exists());
+    }
+
+    #[test]
+    fn gc_on_missing_dir_is_zero() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        let now = chrono::Utc::now();
+        assert_eq!(gc_injected_sets(&h, 14, now).unwrap(), 0);
+    }
+}

package/src/storage/memory/mod.rs

@@ -0,0 +1,235 @@
+//! Persistence for project memories under `.handoff/memory/`.
+//!
+//! Layout:
+//!
+//! ```text
+//! .handoff/memory/
+//!   m-YYYYMMDD-HHMMSS-NNNNNN.json   # one memory per file
+//!   injected/
+//!     <hook_session_id>.json        # per-session "already injected" sidecar (P2)
+//! ```
+//!
+//! All writes go through [`crate::storage::atomic_write`] so the VSCode
+//! extension (which reads `.handoff/`) never observes a torn file. Reads are
+//! lenient: a single corrupt or unparseable file is skipped, not fatal, so one
+//! bad memory can't break the whole feature.
+
+pub mod injected;
+pub mod model;
+
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+
+pub use injected::{
+    gc_injected_sets, injected_path, read_injected_set, write_injected_set, InjectedSet,
+};
+pub use model::{is_valid_memory_kind, MemoryEntry, VALID_MEMORY_KINDS};
+
+/// Path to the `memory/` directory inside a `.handoff/` dir.
+pub fn memory_dir(handoff_dir: &Path) -> PathBuf {
+    handoff_dir.join("memory")
+}
+
+/// Generate a fresh memory id (`m-YYYYMMDD-HHMMSS-NNNNNN`) from the current time.
+pub fn new_memory_id() -> String {
+    let now = chrono::Utc::now();
+    format!("m-{}", now.format("%Y%m%d-%H%M%S-%6f"))
+}
+
+/// Current time as an RFC3339 string (helper so handlers don't import chrono).
+pub fn now_rfc3339() -> String {
+    chrono::Utc::now().to_rfc3339()
+}
+
+/// Ensure `memory/` exists, creating it lazily. This is what makes the feature
+/// backward-compatible with projects initialized before v0.13.0: they never had
+/// a `memory/` dir, and the first `memory_save` creates it.
+pub fn ensure_memory_dir(handoff_dir: &Path) -> Result<PathBuf> {
+    let dir = memory_dir(handoff_dir);
+    std::fs::create_dir_all(&dir)
+        .with_context(|| format!("Failed to create memory dir: {}", dir.display()))?;
+    Ok(dir)
+}
+
+/// Write a memory to `memory/<id>.json` atomically.
+pub fn write_memory(handoff_dir: &Path, entry: &MemoryEntry) -> Result<PathBuf> {
+    let dir = ensure_memory_dir(handoff_dir)?;
+    let file_path = dir.join(format!("{}.json", entry.id));
+    let content = serde_json::to_string_pretty(entry).context("Failed to serialize memory")?;
+    crate::storage::atomic_write(&file_path, content.as_bytes())
+        .with_context(|| format!("Failed to write memory: {}", file_path.display()))?;
+    Ok(file_path)
+}
+
+/// Read every memory in `memory/`, skipping any file that fails to parse. The
+/// `injected/` subdirectory and any non-`.json` files are ignored. Returns an
+/// empty vec when the directory does not exist (uninitialized projects).
+pub fn read_all_memories(handoff_dir: &Path) -> Result<Vec<MemoryEntry>> {
+    let dir = memory_dir(handoff_dir);
+    if !dir.exists() {
+        return Ok(Vec::new());
+    }
+
+    let mut entries: Vec<_> = std::fs::read_dir(&dir)
+        .with_context(|| format!("Failed to read memory dir: {}", dir.display()))?
+        .filter_map(|e| e.ok())
+        .collect();
+    entries.sort_by_key(|e| e.file_name());
+
+    let mut memories = Vec::new();
+    for entry in entries {
+        let path = entry.path();
+        if !path.is_file() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().to_string();
+        if !name.ends_with(".json") || name.starts_with('.') {
+            continue;
+        }
+        let content = match std::fs::read_to_string(&path) {
+            Ok(c) => c,
+            Err(_) => continue,
+        };
+        if let Ok(mem) = serde_json::from_str::<MemoryEntry>(&content) {
+            memories.push(mem);
+        }
+        // Unparseable file: skip silently (lenient read).
+    }
+    Ok(memories)
+}
+
+/// Read one memory by id. Matches the full id first, then falls back to a unique
+/// prefix match (mirrors the referral lookup ergonomics). Returns `Ok(None)`
+/// when nothing matches, and errors on an ambiguous prefix.
+pub fn read_memory_by_id(handoff_dir: &Path, id: &str) -> Result<Option<MemoryEntry>> {
+    let memories = read_all_memories(handoff_dir)?;
+    let mut prefix_matches: Vec<MemoryEntry> = Vec::new();
+    for mem in memories {
+        if mem.id == id {
+            return Ok(Some(mem));
+        }
+        if mem.id.starts_with(id) {
+            prefix_matches.push(mem);
+        }
+    }
+    match prefix_matches.len() {
+        0 => Ok(None),
+        1 => Ok(prefix_matches.into_iter().next()),
+        n => {
+            anyhow::bail!("Ambiguous memory id prefix '{id}' matches {n} memories; use the full id")
+        }
+    }
+}
+
+/// Delete a memory file by exact id. Returns `Ok(false)` when the file does not
+/// exist.
+pub fn delete_memory(handoff_dir: &Path, id: &str) -> Result<bool> {
+    let path = memory_dir(handoff_dir).join(format!("{id}.json"));
+    if !path.exists() {
+        return Ok(false);
+    }
+    std::fs::remove_file(&path)
+        .with_context(|| format!("Failed to delete memory: {}", path.display()))?;
+    Ok(true)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn handoff(tmp: &TempDir) -> PathBuf {
+        let dir = tmp.path().join(".handoff");
+        std::fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    fn sample(id: &str, text: &str) -> MemoryEntry {
+        MemoryEntry::new(
+            id.to_string(),
+            text.to_string(),
+            "lesson".to_string(),
+            vec![],
+            vec![],
+            now_rfc3339(),
+        )
+    }
+
+    #[test]
+    fn write_then_read_roundtrip() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        let mem = sample("m-1", "always use atomic_write");
+        write_memory(&h, &mem).unwrap();
+
+        let all = read_all_memories(&h).unwrap();
+        assert_eq!(all.len(), 1);
+        assert_eq!(all[0].id, "m-1");
+        assert_eq!(all[0].text, "always use atomic_write");
+        assert_eq!(all[0].content_hash, mem.content_hash);
+    }
+
+    #[test]
+    fn read_missing_dir_is_empty() {
+        let tmp = TempDir::new().unwrap();
+        let h = tmp.path().join(".handoff");
+        std::fs::create_dir_all(&h).unwrap();
+        assert!(read_all_memories(&h).unwrap().is_empty());
+    }
+
+    #[test]
+    fn lenient_read_skips_corrupt_file() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        write_memory(&h, &sample("m-1", "good")).unwrap();
+        // Drop a non-JSON file into memory/.
+        std::fs::write(memory_dir(&h).join("m-bad.json"), b"{not json").unwrap();
+
+        let all = read_all_memories(&h).unwrap();
+        assert_eq!(all.len(), 1, "corrupt file must be skipped, good one kept");
+    }
+
+    #[test]
+    fn read_by_id_exact_and_prefix() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        write_memory(&h, &sample("m-20260627-aaa", "a")).unwrap();
+        write_memory(&h, &sample("m-20260627-bbb", "b")).unwrap();
+
+        assert!(read_memory_by_id(&h, "m-20260627-aaa").unwrap().is_some());
+        // Unique prefix
+        let p = read_memory_by_id(&h, "m-20260627-a").unwrap();
+        assert_eq!(p.unwrap().id, "m-20260627-aaa");
+    }
+
+    #[test]
+    fn read_by_id_ambiguous_prefix_errors() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        write_memory(&h, &sample("m-x1", "a")).unwrap();
+        write_memory(&h, &sample("m-x2", "b")).unwrap();
+        assert!(read_memory_by_id(&h, "m-x").is_err());
+    }
+
+    #[test]
+    fn delete_removes_file() {
+        let tmp = TempDir::new().unwrap();
+        let h = handoff(&tmp);
+        write_memory(&h, &sample("m-1", "a")).unwrap();
+        assert!(delete_memory(&h, "m-1").unwrap());
+        assert!(read_all_memories(&h).unwrap().is_empty());
+        // Second delete reports not-found.
+        assert!(!delete_memory(&h, "m-1").unwrap());
+    }
+
+    #[test]
+    fn lazy_dir_creation() {
+        let tmp = TempDir::new().unwrap();
+        let h = tmp.path().join(".handoff");
+        std::fs::create_dir_all(&h).unwrap();
+        assert!(!memory_dir(&h).exists());
+        write_memory(&h, &sample("m-1", "a")).unwrap();
+        assert!(memory_dir(&h).exists());
+    }
+}

package/src/storage/memory/model.rs

@@ -0,0 +1,96 @@
+use serde::{Deserialize, Serialize};
+
+/// Current memory schema version. Bump when `MemoryEntry` changes shape in a way
+/// that needs migration handling on read.
+pub const MEMORY_SCHEMA_VERSION: u32 = 1;
+
+/// Valid `kind` values for a memory. Free-form text is rejected so the field
+/// stays a small, queryable enumeration.
+pub const VALID_MEMORY_KINDS: &[&str] = &["lesson", "rule", "convention", "gotcha"];
+
+/// Returns true if `kind` is one of the accepted memory kinds.
+pub fn is_valid_memory_kind(kind: &str) -> bool {
+    VALID_MEMORY_KINDS.contains(&kind)
+}
+
+/// A single persisted memory: a long-lived, cross-session piece of project
+/// knowledge ("lesson / rule / convention / gotcha"). One file per memory under
+/// `.handoff/memory/`.
+///
+/// Token sets are intentionally **not** stored — they are recomputed from `text`
+/// on every read so the index can never drift from the body.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MemoryEntry {
+    /// Schema version (= [`MEMORY_SCHEMA_VERSION`]).
+    pub version: u32,
+    /// Stable id: `m-YYYYMMDD-HHMMSS-NNNNNN`.
+    pub id: String,
+    /// The memory body (multilingual).
+    pub text: String,
+    /// One of [`VALID_MEMORY_KINDS`].
+    pub kind: String,
+    /// Free-form tags; also fed into the similarity index.
+    #[serde(default)]
+    pub tags: Vec<String>,
+    /// Path prefixes this memory applies to (e.g. `src/storage/`). A query whose
+    /// file paths start with one of these gets a relevance boost.
+    #[serde(default)]
+    pub scope_paths: Vec<String>,
+    /// FNV-1a hash of the canonical (tokenized) text. Drives exact-duplicate
+    /// detection and per-session re-injection tracking.
+    pub content_hash: String,
+    /// RFC3339 creation timestamp.
+    pub created_at: String,
+    /// RFC3339 last-update timestamp.
+    pub updated_at: String,
+    /// RFC3339 timestamp of the last time this memory was injected into a
+    /// session, if ever.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub last_referenced_at: Option<String>,
+    /// Number of times this memory has been injected.
+    #[serde(default)]
+    pub hit_count: u64,
+    /// Ids of memories merged into this one (audit trail for AI-driven merges).
+    #[serde(default)]
+    pub superseded_ids: Vec<String>,
+}
+
+impl MemoryEntry {
+    /// Build a new entry with timestamps and content hash filled in. `now` is an
+    /// RFC3339 timestamp supplied by the caller (keeps this module clock-free
+    /// and testable).
+    pub fn new(
+        id: String,
+        text: String,
+        kind: String,
+        tags: Vec<String>,
+        scope_paths: Vec<String>,
+        now: String,
+    ) -> Self {
+        let content_hash = lexsim::content_hash(&text);
+        MemoryEntry {
+            version: MEMORY_SCHEMA_VERSION,
+            id,
+            text,
+            kind,
+            tags,
+            scope_paths,
+            content_hash,
+            created_at: now.clone(),
+            updated_at: now,
+            last_referenced_at: None,
+            hit_count: 0,
+            superseded_ids: Vec::new(),
+        }
+    }
+
+    /// The text used for similarity: body plus tags (tags carry intent that may
+    /// not appear verbatim in the body).
+    pub fn index_text(&self) -> String {
+        if self.tags.is_empty() {
+            self.text.clone()
+        } else {
+            format!("{} {}", self.text, self.tags.join(" "))
+        }
+    }
+}

package/src/storage/mod.rs

@@ -1,5 +1,6 @@
 pub mod config;
 pub mod git;
+pub mod memory;
 pub mod referrals;
 pub mod sessions;
 pub mod tasks;
@@ -85,6 +86,7 @@ pub fn init_handoff(project_dir: &Path, project_name: &str, description: &str) -
 
     std::fs::create_dir_all(dir.join("sessions")).context("Failed to create .handoff/sessions/")?;
     std::fs::create_dir_all(dir.join("tasks")).context("Failed to create .handoff/tasks/")?;
+    std::fs::create_dir_all(dir.join("memory")).context("Failed to create .handoff/memory/")?;
 
     let config = config::Config::new(project_name, description);
     config::write_config(&dir.join("config.toml"), &config)?;