supercode_harness/

memory.rs

//! ORCH-12 — the `memory` noun at the OBSERVED tier: read and search the
//! persistent cross-session memory documents a harness keeps on disk.
//!
//! supercode never runs a memory engine (charter). There is no index, no
//! embedding, no ranking here: `show` opens the files the harness's own
//! loader opens and reports them; `search` is a plain substring (or, opt-in,
//! a regular-expression) scan over those same files. Every mutation —
//! `hermes memory off`, `openclaw memory forget|reset`, Claude Code's
//! `/memory` — stays the harness's own verb.
//!
//! Three harnesses have a memory store at the pinned versions, each read
//! from its own primary source:
//!
//! * **Claude Code** — the Claude-maintained per-project auto-memory
//!   directory `<claude home>/projects/<encoded-cwd>/memory/`: a `MEMORY.md`
//!   index plus one file per topic
//!   (`docs/composable-harness/inventory/claude-code.md` §2 "Auto memory",
//!   `docs:memory#auto-memory`). The directory is keyed by the enclosing git
//!   repository and shared across its worktrees, so the project is resolved
//!   from the repo root of `cwd`. Relocation via the `autoMemoryDirectory`
//!   setting is NOT modelled; name a relocated directory directly with
//!   `profile` (an absolute path is accepted).
//! * **Hermes 0.21.0** — `get_memory_dir()` is `get_hermes_home()/"memories"`
//!   holding `MEMORY.md` (the agent's own notes) and `USER.md` (what it knows
//!   about the user) (`tools/memory_tool.py:55-57`, `hermes_cli/web_server.py`
//!   memory-status endpoint, both at tag `v2026.7.20`). Profile mode points
//!   `HERMES_HOME` at `<root>/profiles/<name>`, so every profile home is read
//!   the same way. The root-level `MEMORY.md`/`USER.md` names Hermes's own
//!   profile export manifest lists (`hermes_cli/profiles.py:238`) are read
//!   too, so an install that still keeps them there is not silently empty.
//! * **OpenClaw 2026.7.1-2** — the bundled `memory-core` extension's memory
//!   files are, verbatim from its own classifier
//!   (`extensions/memory-core/src/memory/qmd-manager.ts:156-165` at tag
//!   `v2026.7.1-2`), `MEMORY.md`, `DREAMS.md`/`dreams.md`, and everything
//!   under `memory/` — all relative to the AGENT WORKSPACE
//!   ([`openclaw_workspace`], transcribed from `resolveAgentWorkspaceDir`).
//!   `openclaw memory search`
//!   is that extension's own door over the same files; supercode reads the
//!   files rather than shelling out, so no gateway or index is required.
//!
//! Codex, opencode and pi have no memory store at the pinned versions
//! (`docs/composable-harness/inventory/orchestration.md` row 14 — pi is
//! config-only), so they are refused with [`MemoryError::UnsupportedHarness`],
//! never answered with an empty list.

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

use serde::{Deserialize, Serialize};

use crate::{HarnessHomes, HarnessId};

/// Stable row schema shared by Rust, JSON-RPC, the SDKs, and the CLI.
pub const MEMORY_SCHEMA: &str = "supercode.memory.v1";

/// Harnesses with a memory store supercode reads, in product order. Every
/// other harness id is [`MemoryError::UnsupportedHarness`].
pub const MEMORY_HARNESSES: &[&str] = &[
    HarnessId::CLAUDE_CODE,
    HarnessId::HERMES,
    HarnessId::OPENCLAW,
];

/// Hermes's implicit profile — `HERMES_HOME` itself.
const HERMES_DEFAULT_PROFILE: &str = crate::profiles::HERMES_DEFAULT_PROFILE;

/// Lines of a document returned as its `preview`. A memory file is the
/// user's own prose; the default answer names it and shows its head, never
/// its whole body.
const PREVIEW_LINES: usize = 5;
/// Characters kept from one previewed or matched line.
const EXCERPT_CHARS: usize = 200;
/// Bytes read from one memory document. Far above any real memory file, and
/// a ceiling so a mistaken path cannot hang a read.
const MAX_DOCUMENT_BYTES: usize = 1024 * 1024;
/// How deep a memory directory is walked (`memory/topic/notes.md`).
const MAX_WALK_DEPTH: usize = 4;
/// Ceiling on documents from one home.
const MAX_DOCUMENTS: usize = 512;
/// Ceiling on match rows from one search.
const MAX_MATCHES: usize = 512;
/// Extensions a memory document may have. Memory homes sit beside config and
/// credentials; only prose files are ever opened.
const DOCUMENT_EXTENSIONS: &[&str] = &["md", "markdown", "txt"];

/// Which config home a memory document belongs to, in the vocabulary shared
/// by all three harnesses.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemoryScope {
    /// The user's own config home (Hermes's implicit `default` profile).
    User,
    /// A per-project store (Claude Code's auto-memory directory).
    Project,
    /// A named Hermes profile home.
    Profile,
    /// An OpenClaw agent's workspace.
    Agent,
}

impl MemoryScope {
    /// Stable wire spelling, identical to the serde representation.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::User => "user",
            Self::Project => "project",
            Self::Profile => "profile",
            Self::Agent => "agent",
        }
    }
}

/// One memory document, as one harness holds it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemoryDocument {
    /// Path relative to the store's own root (`MEMORY.md`,
    /// `memories/2026-09-01-notes.md`).
    pub name: String,
    /// Owning harness id.
    pub harness: String,
    /// Which config home this document belongs to.
    pub scope: MemoryScope,
    /// Profile / agent / project this store belongs to, when the harness
    /// names one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub profile: Option<String>,
    /// Absolute path of the document.
    pub path: PathBuf,
    /// Size on disk, in bytes.
    pub size: u64,
    /// Last modification time, RFC3339 UTC; `None` when the filesystem does
    /// not report one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub updated_at: Option<String>,
    /// First [`PREVIEW_LINES`] lines, each clipped to [`EXCERPT_CHARS`].
    pub preview: Vec<String>,
    /// Whether the document has more than the preview shows.
    pub truncated: bool,
    /// Whole document text, only when the caller asked for `full`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub content: Option<String>,
}

/// One line of one memory document that matched a search.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemoryMatch {
    /// Owning harness id.
    pub harness: String,
    /// Which config home the document belongs to.
    pub scope: MemoryScope,
    /// Profile / agent / project the store belongs to.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub profile: Option<String>,
    /// Path relative to the store's own root.
    pub name: String,
    /// Absolute path of the document.
    pub path: PathBuf,
    /// 1-based line number of the match.
    pub line: usize,
    /// The matching line, clipped to [`EXCERPT_CHARS`].
    pub excerpt: String,
}

/// `harness.v1.memory.show` request.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(default)]
pub struct MemoryQuery {
    /// Harness whose store is read. Required — memory documents are the
    /// user's own prose, so nothing is read without an explicit target.
    pub harness: String,
    /// Hermes profile, OpenClaw agent id, or Claude Code project directory
    /// (its slug, or an absolute path to a memory directory). `None` reads
    /// every store the harness has.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub profile: Option<String>,
    /// A Claude Code session id, used to resolve which project directory's
    /// auto-memory to read. Rejected for the other harnesses, whose stores
    /// are profile-scoped rather than session-scoped.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session: Option<String>,
    /// Include each document's whole text. Off by default: `show` names the
    /// documents and previews their heads.
    pub full: bool,
    /// Working tree whose project store is read (Claude Code). Defaults to
    /// the process working directory.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cwd: Option<PathBuf>,
    /// Storage roots to read.
    pub homes: HarnessHomes,
}

impl Default for MemoryQuery {
    fn default() -> Self {
        Self {
            harness: String::new(),
            profile: None,
            session: None,
            full: false,
            cwd: None,
            homes: HarnessHomes::default(),
        }
    }
}

/// `harness.v1.memory.search` request.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(default)]
pub struct MemorySearchQuery {
    /// Harness whose store is searched. Required, as for `show`.
    pub harness: String,
    /// The needle. Case-insensitive substring by default.
    pub query: String,
    /// Restrict to one profile / agent / project.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub profile: Option<String>,
    /// Treat `query` as a regular expression instead of a literal.
    pub regex: bool,
    /// Working tree whose project store is searched (Claude Code).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cwd: Option<PathBuf>,
    /// Storage roots to read.
    pub homes: HarnessHomes,
}

impl Default for MemorySearchQuery {
    fn default() -> Self {
        Self {
            harness: String::new(),
            query: String::new(),
            profile: None,
            regex: false,
            cwd: None,
            homes: HarnessHomes::default(),
        }
    }
}

/// Read-only memory failures.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum MemoryError {
    /// The harness has no memory store supercode reads.
    #[error("harness `{harness}` has no memory store (memory exists for: {})", MEMORY_HARNESSES.join(", "))]
    UnsupportedHarness {
        /// The harness id that was asked for.
        harness: String,
    },
    /// The harness has memory stores, but not for this profile / agent /
    /// project.
    #[error("`{harness}` has no memory store for `{profile}`")]
    UnknownProfile {
        /// Harness that was searched.
        harness: String,
        /// Profile / agent / project that was asked for.
        profile: String,
    },
    /// `session` only selects a store for Claude Code.
    #[error(
        "`{harness}` scopes memory by profile, not by session — drop `session` or use `profile`"
    )]
    SessionNotScoped {
        /// Harness that was asked for.
        harness: String,
    },
    /// No Claude Code project directory holds that session.
    #[error("no Claude Code project directory holds session `{session}`")]
    SessionNotFound {
        /// The session id that was asked for.
        session: String,
    },
    /// An empty needle would match every line.
    #[error("memory search needs a query")]
    EmptyQuery,
    /// `regex` was set and the pattern does not compile.
    #[error("`{pattern}` is not a valid regular expression: {reason}")]
    BadRegex {
        /// The pattern as given.
        pattern: String,
        /// The compiler's complaint.
        reason: String,
    },
}

/// Whether supercode reads a memory store for this harness.
pub fn supports_memory(harness: &str) -> bool {
    MEMORY_HARNESSES.contains(&harness)
}

/// Read the memory documents the query selects.
///
/// Read-only: nothing here creates, writes, or removes a path.
pub fn show_memory(query: &MemoryQuery) -> Result<Vec<MemoryDocument>, MemoryError> {
    let stores = resolve_stores(
        &query.harness,
        query.profile.as_deref(),
        query.session.as_deref(),
        query.cwd.as_deref(),
        &query.homes,
    )?;
    let mut documents = Vec::new();
    for store in &stores {
        for (name, path) in store.documents() {
            if documents.len() >= MAX_DOCUMENTS {
                return Ok(documents);
            }
            documents.push(read_document(store, name, &path, query.full));
        }
    }
    Ok(documents)
}

/// Search the same documents [`show_memory`] reports, line by line.
///
/// No engine: a case-insensitive substring scan, or a regular expression
/// when `regex` is set.
pub fn search_memory(query: &MemorySearchQuery) -> Result<Vec<MemoryMatch>, MemoryError> {
    if query.query.trim().is_empty() {
        return Err(MemoryError::EmptyQuery);
    }
    let stores = resolve_stores(
        &query.harness,
        query.profile.as_deref(),
        None,
        query.cwd.as_deref(),
        &query.homes,
    )?;
    let pattern = if query.regex {
        Some(
            regex::RegexBuilder::new(&query.query)
                .case_insensitive(true)
                .build()
                .map_err(|error| MemoryError::BadRegex {
                    pattern: query.query.clone(),
                    reason: error.to_string(),
                })?,
        )
    } else {
        None
    };
    let needle = query.query.to_lowercase();
    let mut matches = Vec::new();
    for store in &stores {
        for (name, path) in store.documents() {
            let Some(text) = read_capped(&path) else {
                continue;
            };
            for (index, line) in text.lines().enumerate() {
                let hit = match &pattern {
                    Some(regex) => regex.is_match(line),
                    None => line.to_lowercase().contains(&needle),
                };
                if !hit {
                    continue;
                }
                matches.push(MemoryMatch {
                    harness: store.harness.to_string(),
                    scope: store.scope,
                    profile: store.profile.clone(),
                    name: name.clone(),
                    path: path.clone(),
                    line: index + 1,
                    excerpt: clip(line),
                });
                if matches.len() >= MAX_MATCHES {
                    return Ok(matches);
                }
            }
        }
    }
    Ok(matches)
}

// ---------------------------------------------------------------------------
// Stores
// ---------------------------------------------------------------------------

/// One harness's memory store for one profile / agent / project: a root plus
/// the file names that harness's own loader treats as memory.
#[derive(Debug, Clone)]
struct MemoryStore {
    harness: &'static str,
    scope: MemoryScope,
    profile: Option<String>,
    /// The store's own root; document names are relative to it.
    root: PathBuf,
    /// The named files this harness treats as memory, in its own order.
    files: Vec<PathBuf>,
    /// Directories walked for further memory documents.
    directories: Vec<PathBuf>,
}

impl MemoryStore {
    /// Every `(name, absolute path)` this store holds, deduplicated and in a
    /// stable order: the named files first (they are the indexes), then the
    /// walked directories.
    fn documents(&self) -> Vec<(String, PathBuf)> {
        let mut out: Vec<(String, PathBuf)> = Vec::new();
        for path in &self.files {
            if path.is_file() {
                out.push((self.relative(path), path.clone()));
            }
        }
        for directory in &self.directories {
            let mut found = Vec::new();
            walk_documents(directory, 0, &mut found);
            found.sort();
            for path in found {
                if !out.iter().any(|(_, existing)| *existing == path) {
                    out.push((self.relative(&path), path));
                }
            }
        }
        out
    }

    /// A document's name: its path relative to the store's own root.
    fn relative(&self, path: &Path) -> String {
        path.strip_prefix(&self.root)
            .unwrap_or(path)
            .to_string_lossy()
            .replace('\\', "/")
    }
}

/// Resolve every store the request selects, or the reason there is none.
fn resolve_stores(
    harness: &str,
    profile: Option<&str>,
    session: Option<&str>,
    cwd: Option<&Path>,
    homes: &HarnessHomes,
) -> Result<Vec<MemoryStore>, MemoryError> {
    if !supports_memory(harness) {
        return Err(MemoryError::UnsupportedHarness {
            harness: harness.to_string(),
        });
    }
    if session.is_some() && harness != HarnessId::CLAUDE_CODE {
        return Err(MemoryError::SessionNotScoped {
            harness: harness.to_string(),
        });
    }
    let stores = match harness {
        HarnessId::CLAUDE_CODE => claude_code_stores(homes, profile, session, cwd)?,
        HarnessId::HERMES => hermes_stores(homes, profile)?,
        HarnessId::OPENCLAW => openclaw_stores(homes, profile)?,
        _ => Vec::new(),
    };
    Ok(stores)
}

// ---------------------------------------------------------------------------
// Claude Code — the per-project auto-memory directory
// ---------------------------------------------------------------------------

/// Claude Code's auto-memory lives in the project directory that also holds
/// the project's transcripts: `<claude home>/projects/<encoded-cwd>/memory/`,
/// a `MEMORY.md` index plus one file per topic
/// (`inventory/claude-code.md` §2 "Auto memory").
///
/// `homes.claude_code` already points at `<claude home>/projects`, the same
/// root discovery walks.
fn claude_code_stores(
    homes: &HarnessHomes,
    profile: Option<&str>,
    session: Option<&str>,
    cwd: Option<&Path>,
) -> Result<Vec<MemoryStore>, MemoryError> {
    let projects = homes.claude_code.clone();
    let project_dir = if let Some(profile) = profile {
        // An absolute path names a relocated directory directly (the
        // `autoMemoryDirectory` escape hatch); anything else is a project
        // slug under the projects root.
        let candidate = PathBuf::from(profile);
        let dir = if candidate.is_absolute() {
            candidate
        } else {
            projects.join(profile)
        };
        if !dir.is_dir() {
            return Err(MemoryError::UnknownProfile {
                harness: HarnessId::CLAUDE_CODE.to_string(),
                profile: profile.to_string(),
            });
        }
        dir
    } else if let Some(session) = session {
        project_dir_for_session(&projects, session).ok_or_else(|| MemoryError::SessionNotFound {
            session: session.to_string(),
        })?
    } else {
        let cwd = cwd
            .map(Path::to_path_buf)
            .or_else(|| std::env::current_dir().ok())
            .unwrap_or_else(|| PathBuf::from("."));
        // Auto-memory is keyed by the enclosing git repository and shared
        // across its worktrees, so the repo root is the project, not cwd.
        let project = repository_root(&cwd).unwrap_or(cwd);
        projects.join(claude_project_slug(&project))
    };
    // A `memory` subdirectory is the store; a directory that IS one (the
    // relocated case) is used as-is.
    let root = if project_dir.join("memory").is_dir() {
        project_dir.join("memory")
    } else {
        project_dir.clone()
    };
    if !root.is_dir() {
        return Ok(Vec::new());
    }
    Ok(vec![MemoryStore {
        harness: HarnessId::CLAUDE_CODE,
        scope: MemoryScope::Project,
        profile: project_dir
            .file_name()
            .map(|name| name.to_string_lossy().to_string()),
        // `MEMORY.md` is the index Claude Code auto-loads each session; the
        // topic files beside it are read on demand, so the directory itself
        // is walked.
        files: vec![root.join("MEMORY.md")],
        directories: vec![root.clone()],
        root,
    }])
}

/// Claude Code's project directory name: the absolute path with every
/// character outside `[A-Za-z0-9]` replaced by `-` (verified against the
/// directory names under a real `~/.claude/projects`).
fn claude_project_slug(path: &Path) -> String {
    path.to_string_lossy()
        .chars()
        .map(|character| {
            if character.is_ascii_alphanumeric() {
                character
            } else {
                '-'
            }
        })
        .collect()
}

/// The first ancestor of `path` (inclusive) holding a `.git` entry — the key
/// Claude Code's auto-memory directory is shared across worktrees by.
fn repository_root(path: &Path) -> Option<PathBuf> {
    path.ancestors()
        .find(|ancestor| ancestor.join(".git").exists())
        .map(Path::to_path_buf)
}

/// Which project directory holds `<session>.jsonl`.
fn project_dir_for_session(projects: &Path, session: &str) -> Option<PathBuf> {
    let transcript = format!("{session}.jsonl");
    let entries = std::fs::read_dir(projects).ok()?;
    let mut found: Vec<PathBuf> = entries
        .flatten()
        .map(|entry| entry.path())
        .filter(|path| path.is_dir() && path.join(&transcript).is_file())
        .collect();
    found.sort();
    found.into_iter().next()
}

// ---------------------------------------------------------------------------
// Hermes — MEMORY.md / USER.md per profile home
// ---------------------------------------------------------------------------

/// Hermes keeps its built-in memory in `HERMES_HOME/memories/` — `MEMORY.md`
/// (the agent's notes) and `USER.md` (what it knows about the user) —
/// with profile mode pointing `HERMES_HOME` at `<root>/profiles/<name>`.
///
/// `homes.hermes` is the `state.db` path, so its parent is `HERMES_HOME`
/// (the same derivation `crate::profiles` uses).
fn hermes_stores(
    homes: &HarnessHomes,
    profile: Option<&str>,
) -> Result<Vec<MemoryStore>, MemoryError> {
    let Some(home) = homes.hermes.parent() else {
        return Ok(Vec::new());
    };
    let mut stores = Vec::new();
    let mut wanted = vec![(HERMES_DEFAULT_PROFILE.to_string(), home.to_path_buf())];
    if let Ok(entries) = std::fs::read_dir(home.join("profiles")) {
        let mut found: Vec<(String, PathBuf)> = entries
            .flatten()
            .map(|entry| entry.path())
            .filter(|path| path.is_dir())
            .filter_map(|path| {
                let name = path.file_name()?.to_string_lossy().to_string();
                Some((name, path))
            })
            .collect();
        found.sort();
        wanted.extend(found);
    }
    if let Some(profile) = profile {
        wanted.retain(|(name, _)| name == profile);
        if wanted.is_empty() {
            return Err(MemoryError::UnknownProfile {
                harness: HarnessId::HERMES.to_string(),
                profile: profile.to_string(),
            });
        }
    }
    for (name, root) in wanted {
        if !root.is_dir() {
            continue;
        }
        let is_default = name == HERMES_DEFAULT_PROFILE;
        stores.push(MemoryStore {
            harness: HarnessId::HERMES,
            scope: if is_default {
                MemoryScope::User
            } else {
                MemoryScope::Profile
            },
            profile: Some(name),
            // Root-level names are the ones Hermes's own profile export
            // manifest lists; `memories/` is where `get_memory_dir()` writes.
            files: vec![root.join("MEMORY.md"), root.join("USER.md")],
            directories: vec![root.join("memories")],
            root,
        });
    }
    Ok(stores)
}

// ---------------------------------------------------------------------------
// OpenClaw — memory-core's files in the agent workspace
// ---------------------------------------------------------------------------

/// memory-core classifies a workspace-relative path as memory when it is
/// `MEMORY.md`, `DREAMS.md`/`dreams.md`, or under `memory/`
/// (`extensions/memory-core/src/memory/qmd-manager.ts:156-165` at tag
/// `v2026.7.1-2`). The workspace is [`openclaw_workspace`]'s.
fn openclaw_stores(
    homes: &HarnessHomes,
    profile: Option<&str>,
) -> Result<Vec<MemoryStore>, MemoryError> {
    let config = homes.openclaw.clone();
    let agents = crate::profiles::list_profiles(homes, Some(HarnessId::OPENCLAW))
        .unwrap_or_default()
        .into_iter()
        .map(|row| (row.name, row.default))
        .collect::<Vec<_>>();
    let mut wanted: Vec<(String, bool)> = agents;
    if wanted.is_empty() {
        // No config and no agent directories: the default workspace is still
        // where memory-core would look.
        wanted.push((crate::profiles::OPENCLAW_DEFAULT_AGENT.to_string(), true));
    } else if !wanted.iter().any(|(_, is_default)| *is_default) {
        // A config-less install declares no default, but memory-core still
        // resolves ONE agent to the default workspace. Same convention the
        // profile rows use: the agent literally named `main`, else the first.
        let fallback = wanted
            .iter()
            .position(|(name, _)| name == crate::profiles::OPENCLAW_DEFAULT_AGENT)
            .unwrap_or(0);
        wanted[fallback].1 = true;
    }
    if let Some(profile) = profile {
        wanted.retain(|(name, _)| name == profile);
        if wanted.is_empty() {
            return Err(MemoryError::UnknownProfile {
                harness: HarnessId::OPENCLAW.to_string(),
                profile: profile.to_string(),
            });
        }
    }
    let mut stores = Vec::new();
    for (name, is_default) in wanted {
        let root = openclaw_workspace(&config, &name, is_default);
        if !root.is_dir() {
            continue;
        }
        stores.push(MemoryStore {
            harness: HarnessId::OPENCLAW,
            scope: MemoryScope::Agent,
            profile: Some(name),
            files: vec![
                root.join("MEMORY.md"),
                root.join("DREAMS.md"),
                root.join("dreams.md"),
            ],
            directories: vec![root.join("memory")],
            root,
        });
    }
    Ok(stores)
}

/// One agent's workspace directory, per the pinned `resolveAgentWorkspaceDir`
/// precedence (`src/agents/agent-scope-config.ts:181`,
/// `src/agents/workspace-default.ts:12` at tag `v2026.7.1-2`):
///
/// 1. the agent's own `workspace` key in `openclaw.json`;
/// 2. the default agent: `$OPENCLAW_WORKSPACE_DIR`, else
///    `<openclaw home>/workspace`, else `<openclaw home>/workspace-<profile>`
///    when `$OPENCLAW_PROFILE` names a non-default profile;
/// 3. any other agent: `<openclaw home>/workspace-<id>`.
///
/// One deliberate difference, measured against `openclaw memory status` on
/// the pinned CLI: openclaw derives the DEFAULT agent's workspace from
/// `$HOME/.openclaw` while the non-default fallback uses the state dir.
/// supercode hangs both off `homes.openclaw`, the one root every read-only
/// method takes as "this openclaw install" — the same directory unless
/// `OPENCLAW_STATE_DIR` points the state somewhere other than
/// `$HOME/.openclaw`, and the only form a fixture or a probe can target.
fn openclaw_workspace(config: &Path, agent: &str, is_default: bool) -> PathBuf {
    if let Some(configured) = openclaw_configured_workspace(config, agent) {
        return configured;
    }
    if !is_default {
        return config.join(format!("workspace-{agent}"));
    }
    if let Some(explicit) = std::env::var_os("OPENCLAW_WORKSPACE_DIR")
        .map(PathBuf::from)
        .filter(|dir| !dir.as_os_str().is_empty())
    {
        return explicit;
    }
    match std::env::var("OPENCLAW_PROFILE") {
        Ok(profile) if !profile.trim().is_empty() && profile.trim() != "default" => {
            config.join(format!("workspace-{}", profile.trim()))
        }
        _ => config.join("workspace"),
    }
}

/// `agents.list[].workspace` (or `agents.entries.<id>.workspace`) from
/// `openclaw.json`, which openclaw reads as JSON5.
fn openclaw_configured_workspace(config: &Path, agent: &str) -> Option<PathBuf> {
    let document = crate::profiles::read_json5(&config.join("openclaw.json"));
    let agents = document.get("agents")?;
    let entry = agents
        .get("list")
        .and_then(|list| list.as_array())
        .and_then(|list| {
            list.iter()
                .find(|item| item.get("id").and_then(serde_json::Value::as_str) == Some(agent))
        })
        .or_else(|| agents.get("entries").and_then(|entries| entries.get(agent)))?;
    let workspace = entry
        .get("workspace")
        .and_then(serde_json::Value::as_str)?
        .trim();
    if workspace.is_empty() {
        return None;
    }
    Some(expand_home(workspace))
}

/// `~`-relative paths are the shape openclaw's own `resolveUserPath` accepts.
fn expand_home(value: &str) -> PathBuf {
    if let Some(rest) = value.strip_prefix("~/") {
        if let Some(home) = std::env::var_os("HOME") {
            return PathBuf::from(home).join(rest);
        }
    }
    PathBuf::from(value)
}

// ---------------------------------------------------------------------------
// Reading
// ---------------------------------------------------------------------------

/// Collect every memory document under `dir`, bounded in depth and count.
fn walk_documents(dir: &Path, depth: usize, out: &mut Vec<PathBuf>) {
    if depth >= MAX_WALK_DEPTH || out.len() >= MAX_DOCUMENTS {
        return;
    }
    let Ok(entries) = std::fs::read_dir(dir) else {
        return;
    };
    let mut children: Vec<PathBuf> = entries.flatten().map(|entry| entry.path()).collect();
    children.sort();
    for path in children {
        if out.len() >= MAX_DOCUMENTS {
            return;
        }
        let name = path
            .file_name()
            .map(|name| name.to_string_lossy().to_string());
        if name.as_deref().is_some_and(|name| name.starts_with('.')) {
            continue;
        }
        if path.is_dir() {
            walk_documents(&path, depth + 1, out);
        } else if is_document(&path) {
            out.push(path);
        }
    }
}

fn is_document(path: &Path) -> bool {
    path.extension()
        .and_then(|extension| extension.to_str())
        .map(|extension| extension.to_ascii_lowercase())
        .is_some_and(|extension| DOCUMENT_EXTENSIONS.contains(&extension.as_str()))
}

fn read_document(store: &MemoryStore, name: String, path: &Path, full: bool) -> MemoryDocument {
    let metadata = std::fs::metadata(path).ok();
    let size = metadata.as_ref().map_or(0, std::fs::Metadata::len);
    let updated_at = metadata
        .as_ref()
        .and_then(|metadata| metadata.modified().ok())
        .and_then(|modified| modified.duration_since(std::time::UNIX_EPOCH).ok())
        .map(|since| crate::sidecar::ms_to_rfc3339(since.as_millis().min(i64::MAX as u128) as i64));
    let text = read_capped(path);
    let preview: Vec<String> = text
        .as_deref()
        .map(|text| text.lines().take(PREVIEW_LINES).map(clip).collect())
        .unwrap_or_default();
    let truncated = text
        .as_deref()
        .map(|text| text.lines().count() > preview.len())
        .unwrap_or(false)
        || size > MAX_DOCUMENT_BYTES as u64;
    MemoryDocument {
        name,
        harness: store.harness.to_string(),
        scope: store.scope,
        profile: store.profile.clone(),
        path: path.to_path_buf(),
        size,
        updated_at,
        preview,
        truncated,
        content: if full { text } else { None },
    }
}

/// Read at most [`MAX_DOCUMENT_BYTES`] of a document. Binary or unreadable
/// files yield `None` rather than failing the whole listing.
fn read_capped(path: &Path) -> Option<String> {
    use std::io::Read;
    let file = std::fs::File::open(path).ok()?;
    let mut buffer = Vec::new();
    file.take(MAX_DOCUMENT_BYTES as u64)
        .read_to_end(&mut buffer)
        .ok()?;
    String::from_utf8(buffer).ok()
}

fn clip(line: &str) -> String {
    let trimmed = line.trim_end();
    if trimmed.chars().count() <= EXCERPT_CHARS {
        return trimmed.to_string();
    }
    let mut out: String = trimmed.chars().take(EXCERPT_CHARS).collect();
    out.push('…');
    out
}