Skip to content

An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.

Rust
18.1 KB
Raw Blame
//! Per-project persistent memory store.
//!
//! Provides file-based memory storage scoped to each workspace, stored under
//! `~/.claw/projects/<workspace-hash>/memory/`. Each memory entry is a
//! markdown file with YAML frontmatter containing name, description, and type.
//! An index file (`MEMORY.md`) provides a summary loaded into conversation
//! context.

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

use crate::config::default_config_home;
use crate::session_control::workspace_fingerprint;

const INDEX_FILENAME: &str = "MEMORY.md";
const INDEX_MAX_LINES: usize = 200;

/// Categorizes what kind of information a memory entry holds.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemoryType {
    /// Information about the user's role, goals, and preferences.
    User,
    /// Guidance on how to approach work — corrections and confirmations.
    Feedback,
    /// Ongoing project context not derivable from code or git.
    Project,
    /// Pointers to where information lives in external systems.
    Reference,
    /// Unrecognized or missing type field.
    Unknown,
}

impl MemoryType {
    fn from_str(s: &str) -> Self {
        match s.trim().to_ascii_lowercase().as_str() {
            "user" => Self::User,
            "feedback" => Self::Feedback,
            "project" => Self::Project,
            "reference" => Self::Reference,
            _ => Self::Unknown,
        }
    }

    /// Returns the canonical string representation used in frontmatter.
    #[must_use]
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::User => "user",
            Self::Feedback => "feedback",
            Self::Project => "project",
            Self::Reference => "reference",
            Self::Unknown => "unknown",
        }
    }
}

/// Metadata parsed from a single memory file's YAML frontmatter.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MemoryEntry {
    /// Kebab-case identifier slug from the `name:` field.
    pub name: String,
    /// One-line summary used for relevance matching.
    pub description: String,
    /// Category of this memory entry.
    pub memory_type: MemoryType,
    /// Filesystem path to the memory file.
    pub path: PathBuf,
}

/// Manages the memory directory for a specific workspace.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MemoryStore {
    memory_dir: PathBuf,
    workspace_root: PathBuf,
}

impl MemoryStore {
    /// Create a `MemoryStore` for the given workspace root.
    ///
    /// The memory directory is resolved as:
    /// `~/.claw/projects/<workspace_fingerprint>/memory/`
    #[must_use]
    pub fn for_workspace(workspace_root: &Path) -> Self {
        let canonical =
            fs::canonicalize(workspace_root).unwrap_or_else(|_| workspace_root.to_path_buf());
        let fingerprint = workspace_fingerprint(&canonical);
        let memory_dir = default_config_home()
            .join("projects")
            .join(fingerprint)
            .join("memory");
        Self {
            memory_dir,
            workspace_root: canonical,
        }
    }

    /// Create a `MemoryStore` with an explicit memory directory path.
    /// Useful for testing.
    #[must_use]
    pub fn with_dir(memory_dir: PathBuf, workspace_root: PathBuf) -> Self {
        Self {
            memory_dir,
            workspace_root,
        }
    }

    /// The resolved memory directory path.
    #[must_use]
    pub fn memory_dir(&self) -> &Path {
        &self.memory_dir
    }

    /// The workspace root this store is bound to.
    #[must_use]
    pub fn workspace_root(&self) -> &Path {
        &self.workspace_root
    }

    /// Path to the `MEMORY.md` index file.
    #[must_use]
    pub fn index_path(&self) -> PathBuf {
        self.memory_dir.join(INDEX_FILENAME)
    }

    /// Read the `MEMORY.md` index file content, truncated to [`INDEX_MAX_LINES`].
    ///
    /// Returns `None` if the file doesn't exist or is empty.
    #[must_use]
    pub fn index_content(&self) -> Option<String> {
        let content = fs::read_to_string(self.index_path()).ok()?;
        let trimmed = content.trim();
        if trimmed.is_empty() {
            return None;
        }
        Some(truncate_to_lines(trimmed, INDEX_MAX_LINES))
    }

    /// Returns whether the memory directory exists on disk.
    #[must_use]
    pub fn exists(&self) -> bool {
        self.memory_dir.is_dir()
    }

    /// Create the memory directory if it doesn't exist.
    pub fn ensure_dir(&self) -> io::Result<()> {
        fs::create_dir_all(&self.memory_dir)
    }

    /// Count of memory entry files (`.md` files excluding `MEMORY.md`).
    #[must_use]
    pub fn entry_count(&self) -> usize {
        self.list_entry_paths().len()
    }

    /// List all memory entries by scanning the directory and parsing frontmatter.
    ///
    /// Files that fail to parse (no frontmatter, missing required fields) are
    /// silently skipped — a malformed file should not break the system.
    #[must_use]
    pub fn list_entries(&self) -> Vec<MemoryEntry> {
        self.list_entry_paths()
            .into_iter()
            .filter_map(|path| {
                let content = fs::read_to_string(&path).ok()?;
                parse_memory_frontmatter(&content, path)
            })
            .collect()
    }

    /// List paths of all `.md` files in the memory directory, excluding
    /// the index file. Returns an empty vec if the directory doesn't exist.
    fn list_entry_paths(&self) -> Vec<PathBuf> {
        let entries = match fs::read_dir(&self.memory_dir) {
            Ok(entries) => entries,
            Err(_) => return Vec::new(),
        };
        let mut paths: Vec<PathBuf> = entries
            .filter_map(Result::ok)
            .map(|entry| entry.path())
            .filter(|path| is_memory_file(path))
            .collect();
        paths.sort();
        paths
    }
}

/// Parse YAML frontmatter from a memory file's content.
///
/// Expected format:
/// ```text
/// ---
/// name: short-kebab-slug
/// description: one-line summary
/// type: user|feedback|project|reference
/// ---
/// ```
///
/// Returns `None` if the file lacks valid frontmatter or the required
/// `name` field.
fn parse_memory_frontmatter(content: &str, path: PathBuf) -> Option<MemoryEntry> {
    let mut lines = content.lines();
    if lines.next().map(str::trim) != Some("---") {
        return None;
    }

    let mut name = None;
    let mut description = None;
    let mut memory_type = MemoryType::Unknown;

    for line in lines {
        let trimmed = line.trim();
        if trimmed == "---" {
            break;
        }
        // Skip indented lines (nested YAML mappings) — only top-level keys matter
        if line.starts_with(' ') || line.starts_with('\t') {
            continue;
        }
        if let Some(value) = strip_frontmatter_key(trimmed, "name") {
            if !value.is_empty() {
                name = Some(value);
            }
        } else if let Some(value) = strip_frontmatter_key(trimmed, "description") {
            if !value.is_empty() {
                description = Some(value);
            }
        } else if let Some(value) = strip_frontmatter_key(trimmed, "type") {
            memory_type = MemoryType::from_str(&value);
        }
    }

    let name = name?;
    Some(MemoryEntry {
        name,
        description: description.unwrap_or_default(),
        memory_type,
        path,
    })
}

/// Extract the value for a top-level YAML key, stripping a single outer quote pair.
fn strip_frontmatter_key(line: &str, key: &str) -> Option<String> {
    let rest = line.strip_prefix(key)?.strip_prefix(':')?;
    let trimmed = rest.trim();
    let value = strip_outer_quotes(trimmed);
    Some(value.to_string())
}

/// Strip a single matching pair of outer quotes (single or double).
fn strip_outer_quotes(s: &str) -> &str {
    let bytes = s.as_bytes();
    if bytes.len() >= 2 {
        let first = bytes[0];
        let last = bytes[bytes.len() - 1];
        if (first == b'"' && last == b'"') || (first == b'\'' && last == b'\'') {
            return &s[1..s.len() - 1];
        }
    }
    s
}

/// Returns `true` if the path is a `.md` file that is not the index.
fn is_memory_file(path: &Path) -> bool {
    if !path.is_file() {
        return false;
    }
    let ext_ok = path
        .extension()
        .and_then(|e| e.to_str())
        .is_some_and(|e| e.eq_ignore_ascii_case("md"));
    let not_index = path
        .file_name()
        .and_then(|f| f.to_str())
        .is_some_and(|f| !f.eq_ignore_ascii_case(INDEX_FILENAME));
    ext_ok && not_index
}

/// Truncate content to at most `max_lines` lines, appending a notice if
/// truncation occurred.
fn truncate_to_lines(content: &str, max_lines: usize) -> String {
    let lines: Vec<&str> = content.lines().collect();
    if lines.len() <= max_lines {
        return content.to_string();
    }
    let truncated: String = lines[..max_lines].join("\n");
    let remaining = lines.len() - max_lines;
    format!("{truncated}\n\n[... {remaining} more lines truncated]")
}

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

    fn temp_dir() -> tempfile::TempDir {
        tempfile::tempdir().unwrap()
    }

    #[test]
    fn for_workspace_produces_stable_path() {
        let workspace = PathBuf::from("/tmp/test-project");
        let store = MemoryStore::with_dir(
            PathBuf::from("/home/user/.claw/projects/abc123/memory"),
            workspace.clone(),
        );
        assert_eq!(store.workspace_root(), workspace);
        assert_eq!(
            store.memory_dir(),
            Path::new("/home/user/.claw/projects/abc123/memory")
        );
    }

    #[test]
    fn index_path_resolves_correctly() {
        let store =
            MemoryStore::with_dir(PathBuf::from("/tmp/memory"), PathBuf::from("/tmp/project"));
        assert_eq!(store.index_path(), PathBuf::from("/tmp/memory/MEMORY.md"));
    }

    #[test]
    fn index_content_returns_none_when_missing() {
        let dir = temp_dir();
        let store = MemoryStore::with_dir(dir.path().join("memory"), dir.path().to_path_buf());
        assert_eq!(store.index_content(), None);
    }

    #[test]
    fn index_content_returns_none_when_empty() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        fs::create_dir_all(&memory_dir).unwrap();
        fs::write(memory_dir.join("MEMORY.md"), "   \n\n  ").unwrap();

        let store = MemoryStore::with_dir(memory_dir, dir.path().to_path_buf());
        assert_eq!(store.index_content(), None);
    }

    #[test]
    fn index_content_truncates_at_limit() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        fs::create_dir_all(&memory_dir).unwrap();

        let lines: Vec<String> = (1..=250).map(|i| format!("- entry {i}")).collect();
        fs::write(memory_dir.join("MEMORY.md"), lines.join("\n")).unwrap();

        let store = MemoryStore::with_dir(memory_dir, dir.path().to_path_buf());
        let content = store.index_content().unwrap();
        assert!(content.contains("- entry 200"));
        assert!(!content.contains("- entry 201"));
        assert!(content.contains("[... 50 more lines truncated]"));
    }

    #[test]
    fn exists_reflects_directory_state() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        let store = MemoryStore::with_dir(memory_dir.clone(), dir.path().to_path_buf());

        assert!(!store.exists());
        fs::create_dir_all(&memory_dir).unwrap();
        assert!(store.exists());
    }

    #[test]
    fn ensure_dir_creates_directory() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("deep").join("nested").join("memory");
        let store = MemoryStore::with_dir(memory_dir.clone(), dir.path().to_path_buf());

        assert!(!memory_dir.exists());
        store.ensure_dir().unwrap();
        assert!(memory_dir.is_dir());
    }

    #[test]
    fn entry_count_with_no_directory() {
        let dir = temp_dir();
        let store = MemoryStore::with_dir(dir.path().join("nonexistent"), dir.path().to_path_buf());
        assert_eq!(store.entry_count(), 0);
    }

    #[test]
    fn entry_count_excludes_index() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        fs::create_dir_all(&memory_dir).unwrap();
        fs::write(memory_dir.join("MEMORY.md"), "# Index").unwrap();
        fs::write(
            memory_dir.join("user_role.md"),
            "---\nname: user-role\ndescription: test\ntype: user\n---\ncontent",
        )
        .unwrap();
        fs::write(
            memory_dir.join("feedback_style.md"),
            "---\nname: feedback-style\ndescription: test2\ntype: feedback\n---\ncontent",
        )
        .unwrap();
        // non-md file should be ignored
        fs::write(memory_dir.join("notes.txt"), "not a memory").unwrap();

        let store = MemoryStore::with_dir(memory_dir, dir.path().to_path_buf());
        assert_eq!(store.entry_count(), 2);
    }

    #[test]
    fn list_entries_parses_frontmatter() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        fs::create_dir_all(&memory_dir).unwrap();
        fs::write(
            memory_dir.join("user_role.md"),
            "---\nname: user-role\ndescription: Senior Rust developer\ntype: user\n---\nDetails here",
        )
        .unwrap();
        fs::write(
            memory_dir.join("feedback_no_comments.md"),
            "---\nname: no-inline-comments\ndescription: Don't add comments to code\ntype: feedback\n---\nWhy: user prefers clean code",
        )
        .unwrap();

        let store = MemoryStore::with_dir(memory_dir, dir.path().to_path_buf());
        let entries = store.list_entries();
        assert_eq!(entries.len(), 2);

        // Entries sorted by filename: feedback_no_comments.md comes first
        let first = &entries[0];
        assert_eq!(first.name, "no-inline-comments");
        assert!(first.path.ends_with("feedback_no_comments.md"));
        assert_eq!(first.memory_type, MemoryType::Feedback);

        let user_entry = entries.iter().find(|e| e.name == "user-role").unwrap();
        assert_eq!(user_entry.description, "Senior Rust developer");
        assert_eq!(user_entry.memory_type, MemoryType::User);
    }

    #[test]
    fn list_entries_skips_malformed_files() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        fs::create_dir_all(&memory_dir).unwrap();

        // Valid entry
        fs::write(
            memory_dir.join("valid.md"),
            "---\nname: valid\ndescription: ok\ntype: project\n---\ncontent",
        )
        .unwrap();
        // No frontmatter
        fs::write(memory_dir.join("no_front.md"), "just content").unwrap();
        // Frontmatter but no name
        fs::write(
            memory_dir.join("no_name.md"),
            "---\ndescription: orphan\ntype: user\n---\ncontent",
        )
        .unwrap();

        let store = MemoryStore::with_dir(memory_dir, dir.path().to_path_buf());
        let entries = store.list_entries();
        assert_eq!(entries.len(), 1);
        assert_eq!(entries[0].name, "valid");
        assert_eq!(entries[0].memory_type, MemoryType::Project);
    }

    #[test]
    fn parse_frontmatter_handles_quoted_values() {
        let content =
            "---\nname: \"quoted-name\"\ndescription: 'single quoted'\ntype: reference\n---\n";
        let entry = parse_memory_frontmatter(content, PathBuf::from("test.md")).unwrap();
        assert_eq!(entry.name, "quoted-name");
        assert_eq!(entry.description, "single quoted");
        assert_eq!(entry.memory_type, MemoryType::Reference);
    }

    #[test]
    fn parse_frontmatter_unknown_type() {
        let content = "---\nname: test\ndescription: desc\ntype: weird\n---\n";
        let entry = parse_memory_frontmatter(content, PathBuf::from("test.md")).unwrap();
        assert_eq!(entry.memory_type, MemoryType::Unknown);
    }

    #[test]
    fn parse_frontmatter_missing_type_defaults_to_unknown() {
        let content = "---\nname: test\ndescription: desc\n---\n";
        let entry = parse_memory_frontmatter(content, PathBuf::from("test.md")).unwrap();
        assert_eq!(entry.memory_type, MemoryType::Unknown);
    }

    #[test]
    fn memory_type_roundtrip() {
        for mt in [
            MemoryType::User,
            MemoryType::Feedback,
            MemoryType::Project,
            MemoryType::Reference,
        ] {
            assert_eq!(MemoryType::from_str(mt.as_str()), mt);
        }
    }

    #[test]
    fn truncate_to_lines_no_op_when_under_limit() {
        let content = "line1\nline2\nline3";
        assert_eq!(truncate_to_lines(content, 10), content);
    }

    #[test]
    fn truncate_to_lines_exact_limit() {
        let content = "a\nb\nc";
        assert_eq!(truncate_to_lines(content, 3), content);
    }

    #[test]
    fn is_memory_file_filters_correctly() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        fs::create_dir_all(&memory_dir).unwrap();
        let md_file = memory_dir.join("user_role.md");
        let index_file = memory_dir.join("MEMORY.md");
        let txt_file = memory_dir.join("notes.txt");
        fs::write(&md_file, "content").unwrap();
        fs::write(&index_file, "index").unwrap();
        fs::write(&txt_file, "text").unwrap();

        assert!(is_memory_file(&md_file));
        assert!(!is_memory_file(&index_file));
        assert!(!is_memory_file(&txt_file));
        assert!(!is_memory_file(&memory_dir)); // directory, not file
    }

    #[test]
    fn list_entries_sorted_alphabetically() {
        let dir = temp_dir();
        let memory_dir = dir.path().join("memory");
        fs::create_dir_all(&memory_dir).unwrap();
        for name in ["zebra.md", "alpha.md", "middle.md"] {
            fs::write(
                memory_dir.join(name),
                format!(
                    "---\nname: {}\ndescription: d\ntype: user\n---\n",
                    name.trim_end_matches(".md")
                ),
            )
            .unwrap();
        }

        let store = MemoryStore::with_dir(memory_dir, dir.path().to_path_buf());
        let names: Vec<_> = store
            .list_entries()
            .iter()
            .map(|e| e.name.clone())
            .collect();
        assert_eq!(names, vec!["alpha", "middle", "zebra"]);
    }
}