Simplify workspace to path-based storage, remove legacy code

- Consolidate all migrations into V1__initial.sql - Replace DocType enum with flexible path-based file storage - Add list_workspace_files SQL function for directory listing - Update memory tools for path-based API (memory_read, memory_write, memory_search, memory_list) - Remove unused OpenAI/Anthropic providers (NEAR AI only) - Simplify config to remove multi-provider support - Update CLAUDE.md documentation Co-Authored-By: Claude Opus 4.5 <[email protected]>
2026-08-30 08:17:53 +00:00 · 2026-02-02 21:38:53 -08:00
parent f29892b3fb
commit 3718cfa767
13 changed files with 877 additions and 1427 deletions
@@ -1,99 +1,32 @@
-//! Memory document types.
+//! Memory document types for the workspace.

 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use uuid::Uuid;

-use crate::error::WorkspaceError;
-
-/// Document type in the workspace.
+/// Well-known document paths.
 ///
-/// Each type represents a different kind of persistent memory:
-/// - **Memory**: Long-term curated facts and decisions (MEMORY.md)
-/// - **DailyLog**: Append-only daily notes (memory/YYYY-MM-DD.md)
-/// - **Identity**: Agent name and personality
-/// - **Soul**: Core values and behavior principles
-/// - **Agents**: Behavior instructions
-/// - **User**: User context (name, preferences)
-/// - **Heartbeat**: Periodic checklist for proactive execution
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum DocType {
-    /// Long-term curated memory (MEMORY.md equivalent).
-    Memory,
-    /// Daily append-only logs.
-    DailyLog,
+/// These are conventional paths that have special meaning in the workspace.
+/// Agents can create arbitrary paths beyond these.
+pub mod paths {
+    /// Long-term curated memory.
+    pub const MEMORY: &str = "MEMORY.md";
    /// Agent identity (name, nature, vibe).
-    Identity,
-    /// Core values and principles (SOUL.md).
-    Soul,
-    /// Behavior instructions (AGENTS.md).
-    Agents,
-    /// User context (USER.md).
-    User,
-    /// Periodic checklist (HEARTBEAT.md).
-    Heartbeat,
-}
-
-impl DocType {
-    /// Get the string representation.
-    pub fn as_str(&self) -> &'static str {
-        match self {
-            DocType::Memory => "memory",
-            DocType::DailyLog => "daily_log",
-            DocType::Identity => "identity",
-            DocType::Soul => "soul",
-            DocType::Agents => "agents",
-            DocType::User => "user",
-            DocType::Heartbeat => "heartbeat",
-        }
-    }
-
-    /// Check if this document type is a singleton (one per user/agent).
-    pub fn is_singleton(&self) -> bool {
-        match self {
-            DocType::Memory
-            | DocType::Identity
-            | DocType::Soul
-            | DocType::Agents
-            | DocType::User
-            | DocType::Heartbeat => true,
-            DocType::DailyLog => false,
-        }
-    }
-
-    /// Check if this document should be included in the system prompt.
-    pub fn is_identity_document(&self) -> bool {
-        matches!(
-            self,
-            DocType::Identity | DocType::Soul | DocType::Agents | DocType::User
-        )
-    }
-}
-
-impl TryFrom<&str> for DocType {
-    type Error = WorkspaceError;
-
-    fn try_from(s: &str) -> Result<Self, Self::Error> {
-        match s {
-            "memory" => Ok(DocType::Memory),
-            "daily_log" => Ok(DocType::DailyLog),
-            "identity" => Ok(DocType::Identity),
-            "soul" => Ok(DocType::Soul),
-            "agents" => Ok(DocType::Agents),
-            "user" => Ok(DocType::User),
-            "heartbeat" => Ok(DocType::Heartbeat),
-            _ => Err(WorkspaceError::InvalidDocType {
-                doc_type: s.to_string(),
-            }),
-        }
-    }
-}
-
-impl std::fmt::Display for DocType {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}", self.as_str())
-    }
+    pub const IDENTITY: &str = "IDENTITY.md";
+    /// Core values and principles.
+    pub const SOUL: &str = "SOUL.md";
+    /// Behavior instructions.
+    pub const AGENTS: &str = "AGENTS.md";
+    /// User context (name, preferences).
+    pub const USER: &str = "USER.md";
+    /// Periodic checklist for heartbeat.
+    pub const HEARTBEAT: &str = "HEARTBEAT.md";
+    /// Root runbook/readme.
+    pub const README: &str = "README.md";
+    /// Daily logs directory.
+    pub const DAILY_DIR: &str = "daily/";
+    /// Context directory (for identity-related docs).
+    pub const CONTEXT_DIR: &str = "context/";
 }

 /// A memory document stored in the database.
@@ -105,10 +38,8 @@ pub struct MemoryDocument {
    pub user_id: String,
    /// Optional agent ID for multi-agent isolation.
    pub agent_id: Option<Uuid>,
-    /// Document type.
-    pub doc_type: DocType,
-    /// Optional title (e.g., date for daily logs).
-    pub title: Option<String>,
+    /// File path within the workspace (e.g., "context/vision.md").
+    pub path: String,
    /// Full document content.
    pub content: String,
    /// Creation timestamp.
@@ -120,20 +51,18 @@ pub struct MemoryDocument {
 }

 impl MemoryDocument {
-    /// Create a new document (not persisted yet).
+    /// Create a new document with a path.
    pub fn new(
        user_id: impl Into<String>,
        agent_id: Option<Uuid>,
-        doc_type: DocType,
-        title: Option<String>,
+        path: impl Into<String>,
    ) -> Self {
        let now = Utc::now();
        Self {
            id: Uuid::new_v4(),
            user_id: user_id.into(),
            agent_id,
-            doc_type,
-            title,
+            path: path.into(),
            content: String::new(),
            created_at: now,
            updated_at: now,
@@ -141,6 +70,17 @@ impl MemoryDocument {
        }
    }

+    /// Get the file name from the path.
+    pub fn file_name(&self) -> &str {
+        self.path.rsplit('/').next().unwrap_or(&self.path)
+    }
+
+    /// Get the parent directory from the path.
+    pub fn parent_dir(&self) -> Option<&str> {
+        let idx = self.path.rfind('/')?;
+        Some(&self.path[..idx])
+    }
+
    /// Check if the document is empty.
    pub fn is_empty(&self) -> bool {
        self.content.is_empty()
@@ -150,6 +90,34 @@ impl MemoryDocument {
    pub fn word_count(&self) -> usize {
        self.content.split_whitespace().count()
    }
+
+    /// Check if this is a well-known identity document.
+    pub fn is_identity_document(&self) -> bool {
+        matches!(
+            self.path.as_str(),
+            paths::IDENTITY | paths::SOUL | paths::AGENTS | paths::USER
+        )
+    }
+}
+
+/// An entry in a workspace directory listing.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceEntry {
+    /// Path relative to listing directory.
+    pub path: String,
+    /// True if this is a directory (has children).
+    pub is_directory: bool,
+    /// Last update timestamp (latest among children for directories).
+    pub updated_at: Option<DateTime<Utc>>,
+    /// Preview of content (first ~200 chars, None for directories).
+    pub content_preview: Option<String>,
+}
+
+impl WorkspaceEntry {
+    /// Get the entry name (last path component).
+    pub fn name(&self) -> &str {
+        self.path.rsplit('/').next().unwrap_or(&self.path)
+    }
 }

 /// A chunk of a memory document for search indexing.
@@ -194,43 +162,60 @@ mod tests {
    use super::*;

    #[test]
-    fn test_doc_type_roundtrip() {
-        for doc_type in [
-            DocType::Memory,
-            DocType::DailyLog,
-            DocType::Identity,
-            DocType::Soul,
-            DocType::Agents,
-            DocType::User,
-            DocType::Heartbeat,
-        ] {
-            let s = doc_type.as_str();
-            let parsed = DocType::try_from(s).unwrap();
-            assert_eq!(parsed, doc_type);
-        }
+    fn test_memory_document_new() {
+        let doc = MemoryDocument::new("user1", None, "context/vision.md");
+        assert_eq!(doc.user_id, "user1");
+        assert_eq!(doc.path, "context/vision.md");
+        assert!(doc.content.is_empty());
    }

    #[test]
-    fn test_singleton_types() {
-        assert!(DocType::Memory.is_singleton());
-        assert!(DocType::Heartbeat.is_singleton());
-        assert!(!DocType::DailyLog.is_singleton());
+    fn test_memory_document_file_name() {
+        let doc = MemoryDocument::new("user1", None, "projects/alpha/README.md");
+        assert_eq!(doc.file_name(), "README.md");
    }

    #[test]
-    fn test_identity_documents() {
-        assert!(DocType::Soul.is_identity_document());
-        assert!(DocType::Agents.is_identity_document());
-        assert!(!DocType::Memory.is_identity_document());
-        assert!(!DocType::DailyLog.is_identity_document());
+    fn test_memory_document_parent_dir() {
+        let doc = MemoryDocument::new("user1", None, "projects/alpha/README.md");
+        assert_eq!(doc.parent_dir(), Some("projects/alpha"));
+
+        let root_doc = MemoryDocument::new("user1", None, "README.md");
+        assert_eq!(root_doc.parent_dir(), None);
    }

    #[test]
    fn test_memory_document_word_count() {
-        let mut doc = MemoryDocument::new("user1", None, DocType::Memory, None);
+        let mut doc = MemoryDocument::new("user1", None, "MEMORY.md");
        assert_eq!(doc.word_count(), 0);

        doc.content = "Hello world, this is a test.".to_string();
        assert_eq!(doc.word_count(), 6);
    }
+
+    #[test]
+    fn test_is_identity_document() {
+        let identity = MemoryDocument::new("user1", None, paths::IDENTITY);
+        assert!(identity.is_identity_document());
+
+        let soul = MemoryDocument::new("user1", None, paths::SOUL);
+        assert!(soul.is_identity_document());
+
+        let memory = MemoryDocument::new("user1", None, paths::MEMORY);
+        assert!(!memory.is_identity_document());
+
+        let custom = MemoryDocument::new("user1", None, "projects/notes.md");
+        assert!(!custom.is_identity_document());
+    }
+
+    #[test]
+    fn test_workspace_entry_name() {
+        let entry = WorkspaceEntry {
+            path: "projects/alpha".to_string(),
+            is_directory: true,
+            updated_at: None,
+            content_preview: None,
+        };
+        assert_eq!(entry.name(), "alpha");
+    }
 }
@@ -1,37 +1,44 @@
 //! Workspace and memory system (OpenClaw-inspired).
 //!
-//! The workspace provides persistent memory for agents:
-//! - **MEMORY.md**: Long-term curated memory (facts, decisions, preferences)
-//! - **Daily logs**: Append-only daily notes (raw context)
-//! - **Identity files**: Agent personality and user context
-//! - **HEARTBEAT.md**: Periodic checklist for proactive execution
+//! The workspace provides persistent memory for agents with a flexible
+//! filesystem-like structure. Agents can create arbitrary markdown file
+//! hierarchies that get indexed for full-text and semantic search.
 //!
-//! Memory is searchable via hybrid search (FTS + semantic embeddings).
-//!
-//! # Architecture
+//! # Filesystem-like API
 //!
 //! ```text
-//! ┌─────────────────────────────────────────────────────────────┐
-//! │                        Workspace                             │
-//! │  ┌────────────────┐  ┌────────────────┐  ┌──────────────┐  │
-//! │  │ MemoryDocument │  │  MemoryChunk   │  │   Search     │  │
-//! │  │ (full docs)    │──│ (chunked)      │──│ (FTS+vector) │  │
-//! │  └────────────────┘  └────────────────┘  └──────────────┘  │
-//! │           │                   │                  │          │
-//! │           └───────────────────┴──────────────────┘          │
-//! │                           │                                  │
-//! │                    ┌──────┴──────┐                          │
-//! │                    │  Repository │                          │
-//! │                    │ (PostgreSQL)│                          │
-//! │                    └─────────────┘                          │
-//! └─────────────────────────────────────────────────────────────┘
+//! workspace/
+//! ├── README.md              <- Root runbook/index
+//! ├── MEMORY.md              <- Long-term curated memory
+//! ├── HEARTBEAT.md           <- Periodic checklist
+//! ├── context/               <- Identity and context
+//! │   ├── vision.md
+//! │   └── priorities.md
+//! ├── daily/                 <- Daily logs
+//! │   ├── 2024-01-15.md
+//! │   └── 2024-01-16.md
+//! ├── projects/              <- Arbitrary structure
+//! │   └── alpha/
+//! │       ├── README.md
+//! │       └── notes.md
+//! └── ...
 //! ```
 //!
+//! # Key Operations
+//!
+//! - `read(path)` - Read a file
+//! - `write(path, content)` - Create or update a file
+//! - `append(path, content)` - Append to a file
+//! - `list(dir)` - List directory contents
+//! - `delete(path)` - Delete a file
+//! - `search(query)` - Full-text + semantic search across all files
+//!
 //! # Key Patterns
 //!
 //! 1. **Memory is persistence**: If you want to remember something, write it
-//! 2. **Two-tier memory**: Daily logs (raw) + MEMORY.md (curated)
-//! 3. **Hybrid search**: Vector similarity + BM25 full-text via RRF
+//! 2. **Flexible structure**: Create any directory/file hierarchy you need
+//! 3. **Self-documenting**: Use README.md files to describe directory structure
+//! 4. **Hybrid search**: Vector similarity + BM25 full-text via RRF

 mod chunker;
 mod document;
@@ -40,7 +47,7 @@ mod repository;
 mod search;

 pub use chunker::{ChunkConfig, chunk_document};
-pub use document::{DocType, MemoryChunk, MemoryDocument};
+pub use document::{MemoryChunk, MemoryDocument, WorkspaceEntry, paths};
 pub use embeddings::{EmbeddingProvider, OpenAiEmbeddings};
 pub use repository::Repository;
 pub use search::{SearchConfig, SearchResult};
@@ -101,15 +108,127 @@ impl Workspace {
        self.agent_id
    }

-    // ==================== Document Access ====================
+    // ==================== File Operations ====================
+
+    /// Read a file by path.
+    ///
+    /// Returns the document if it exists, or an error if not found.
+    ///
+    /// # Example
+    /// ```ignore
+    /// let doc = workspace.read("context/vision.md").await?;
+    /// println!("{}", doc.content);
+    /// ```
+    pub async fn read(&self, path: &str) -> Result<MemoryDocument, WorkspaceError> {
+        let path = normalize_path(path);
+        self.repo
+            .get_document_by_path(&self.user_id, self.agent_id, &path)
+            .await
+    }
+
+    /// Write (create or update) a file.
+    ///
+    /// Creates parent directories implicitly (they're virtual in the DB).
+    /// Re-indexes the document for search after writing.
+    ///
+    /// # Example
+    /// ```ignore
+    /// workspace.write("projects/alpha/README.md", "# Project Alpha\n\nDescription here.").await?;
+    /// ```
+    pub async fn write(&self, path: &str, content: &str) -> Result<MemoryDocument, WorkspaceError> {
+        let path = normalize_path(path);
+        let doc = self
+            .repo
+            .get_or_create_document_by_path(&self.user_id, self.agent_id, &path)
+            .await?;
+        self.repo.update_document(doc.id, content).await?;
+        self.reindex_document(doc.id).await?;
+
+        // Return updated doc
+        self.repo.get_document_by_id(doc.id).await
+    }
+
+    /// Append content to a file.
+    ///
+    /// Creates the file if it doesn't exist.
+    /// Adds a newline separator between existing and new content.
+    pub async fn append(&self, path: &str, content: &str) -> Result<(), WorkspaceError> {
+        let path = normalize_path(path);
+        let doc = self
+            .repo
+            .get_or_create_document_by_path(&self.user_id, self.agent_id, &path)
+            .await?;
+
+        let new_content = if doc.content.is_empty() {
+            content.to_string()
+        } else {
+            format!("{}\n{}", doc.content, content)
+        };
+
+        self.repo.update_document(doc.id, &new_content).await?;
+        self.reindex_document(doc.id).await?;
+        Ok(())
+    }
+
+    /// Check if a file exists.
+    pub async fn exists(&self, path: &str) -> Result<bool, WorkspaceError> {
+        let path = normalize_path(path);
+        match self
+            .repo
+            .get_document_by_path(&self.user_id, self.agent_id, &path)
+            .await
+        {
+            Ok(_) => Ok(true),
+            Err(WorkspaceError::DocumentNotFound { .. }) => Ok(false),
+            Err(e) => Err(e),
+        }
+    }
+
+    /// Delete a file.
+    ///
+    /// Also deletes associated chunks.
+    pub async fn delete(&self, path: &str) -> Result<(), WorkspaceError> {
+        let path = normalize_path(path);
+        self.repo
+            .delete_document_by_path(&self.user_id, self.agent_id, &path)
+            .await
+    }
+
+    /// List files and directories in a path.
+    ///
+    /// Returns immediate children (not recursive).
+    /// Use empty string or "/" for root directory.
+    ///
+    /// # Example
+    /// ```ignore
+    /// let entries = workspace.list("projects/").await?;
+    /// for entry in entries {
+    ///     if entry.is_directory {
+    ///         println!("📁 {}/", entry.name());
+    ///     } else {
+    ///         println!("📄 {}", entry.name());
+    ///     }
+    /// }
+    /// ```
+    pub async fn list(&self, directory: &str) -> Result<Vec<WorkspaceEntry>, WorkspaceError> {
+        let directory = normalize_directory(directory);
+        self.repo
+            .list_directory(&self.user_id, self.agent_id, &directory)
+            .await
+    }
+
+    /// List all files recursively (flat list of all paths).
+    pub async fn list_all(&self) -> Result<Vec<String>, WorkspaceError> {
+        self.repo.list_all_paths(&self.user_id, self.agent_id).await
+    }
+
+    // ==================== Convenience Methods ====================

    /// Get the main MEMORY.md document (long-term curated memory).
    ///
    /// Creates it if it doesn't exist.
    pub async fn memory(&self) -> Result<MemoryDocument, WorkspaceError> {
-        self.repo
-            .get_or_create_document(&self.user_id, self.agent_id, DocType::Memory, None)
-            .await
+        self.read_or_create(paths::MEMORY).await
    }

    /// Get today's daily log.
@@ -122,38 +241,23 @@ impl Workspace {

    /// Get a daily log for a specific date.
    pub async fn daily_log(&self, date: NaiveDate) -> Result<MemoryDocument, WorkspaceError> {
-        let title = date.format("%Y-%m-%d").to_string();
-        self.repo
-            .get_or_create_document(
-                &self.user_id,
-                self.agent_id,
-                DocType::DailyLog,
-                Some(&title),
-            )
-            .await
+        let path = format!("daily/{}.md", date.format("%Y-%m-%d"));
+        self.read_or_create(&path).await
    }

    /// Get the heartbeat checklist (HEARTBEAT.md).
    pub async fn heartbeat_checklist(&self) -> Result<Option<String>, WorkspaceError> {
-        match self
-            .repo
-            .get_document(&self.user_id, self.agent_id, DocType::Heartbeat, None)
-            .await
-        {
+        match self.read(paths::HEARTBEAT).await {
            Ok(doc) => Ok(Some(doc.content)),
            Err(WorkspaceError::DocumentNotFound { .. }) => Ok(None),
            Err(e) => Err(e),
        }
    }

-    /// Get a document by type.
-    pub async fn get_document(
-        &self,
-        doc_type: DocType,
-        title: Option<&str>,
-    ) -> Result<MemoryDocument, WorkspaceError> {
+    /// Helper to read or create a file.
+    async fn read_or_create(&self, path: &str) -> Result<MemoryDocument, WorkspaceError> {
        self.repo
-            .get_document(&self.user_id, self.agent_id, doc_type, title)
+            .get_or_create_document_by_path(&self.user_id, self.agent_id, path)
            .await
    }

@@ -164,6 +268,7 @@ impl Workspace {
    /// This is for important facts, decisions, and preferences worth
    /// remembering long-term.
    pub async fn append_memory(&self, entry: &str) -> Result<(), WorkspaceError> {
+        // Use double newline for memory entries (semantic separation)
        let doc = self.memory().await?;
        let new_content = if doc.content.is_empty() {
            entry.to_string()
@@ -179,34 +284,11 @@ impl Workspace {
    ///
    /// Daily logs are raw, append-only notes for the current day.
    pub async fn append_daily_log(&self, entry: &str) -> Result<(), WorkspaceError> {
-        let doc = self.today_log().await?;
+        let today = Utc::now().date_naive();
+        let path = format!("daily/{}.md", today.format("%Y-%m-%d"));
        let timestamp = Utc::now().format("%H:%M:%S");
        let timestamped_entry = format!("[{}] {}", timestamp, entry);
-
-        let new_content = if doc.content.is_empty() {
-            timestamped_entry
-        } else {
-            format!("{}\n{}", doc.content, timestamped_entry)
-        };
-        self.repo.update_document(doc.id, &new_content).await?;
-        self.reindex_document(doc.id).await?;
-        Ok(())
-    }
-
-    /// Update a document's content entirely.
-    pub async fn update_document(
-        &self,
-        doc_type: DocType,
-        title: Option<&str>,
-        content: &str,
-    ) -> Result<(), WorkspaceError> {
-        let doc = self
-            .repo
-            .get_or_create_document(&self.user_id, self.agent_id, doc_type, title)
-            .await?;
-        self.repo.update_document(doc.id, content).await?;
-        self.reindex_document(doc.id).await?;
-        Ok(())
+        self.append(&path, &timestamped_entry).await
    }

    // ==================== System Prompt ====================
@@ -219,19 +301,15 @@ impl Workspace {
        let mut parts = Vec::new();

        // Load identity files in order of importance
-        let identity_types = [
-            (DocType::Agents, "## Agent Instructions"),
-            (DocType::Soul, "## Core Values"),
-            (DocType::User, "## User Context"),
-            (DocType::Identity, "## Identity"),
+        let identity_files = [
+            (paths::AGENTS, "## Agent Instructions"),
+            (paths::SOUL, "## Core Values"),
+            (paths::USER, "## User Context"),
+            (paths::IDENTITY, "## Identity"),
        ];

-        for (doc_type, header) in identity_types {
-            if let Ok(doc) = self
-                .repo
-                .get_document(&self.user_id, self.agent_id, doc_type, None)
-                .await
-            {
+        for (path, header) in identity_files {
+            if let Ok(doc) = self.read(path).await {
                if !doc.content.is_empty() {
                    parts.push(format!("{}\n\n{}", header, doc.content));
                }
@@ -372,21 +450,50 @@ impl Workspace {
    }
 }

+/// Normalize a file path (remove leading/trailing slashes, collapse //).
+fn normalize_path(path: &str) -> String {
+    let path = path.trim().trim_matches('/');
+    // Collapse multiple slashes
+    let mut result = String::new();
+    let mut last_was_slash = false;
+    for c in path.chars() {
+        if c == '/' {
+            if !last_was_slash {
+                result.push(c);
+            }
+            last_was_slash = true;
+        } else {
+            result.push(c);
+            last_was_slash = false;
+        }
+    }
+    result
+}
+
+/// Normalize a directory path (ensure no trailing slash for consistency).
+fn normalize_directory(path: &str) -> String {
+    let path = normalize_path(path);
+    path.trim_end_matches('/').to_string()
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;

    #[test]
-    fn test_doc_type_display() {
-        assert_eq!(DocType::Memory.as_str(), "memory");
-        assert_eq!(DocType::DailyLog.as_str(), "daily_log");
-        assert_eq!(DocType::Heartbeat.as_str(), "heartbeat");
+    fn test_normalize_path() {
+        assert_eq!(normalize_path("foo/bar"), "foo/bar");
+        assert_eq!(normalize_path("/foo/bar/"), "foo/bar");
+        assert_eq!(normalize_path("foo//bar"), "foo/bar");
+        assert_eq!(normalize_path("  /foo/  "), "foo");
+        assert_eq!(normalize_path("README.md"), "README.md");
    }

    #[test]
-    fn test_doc_type_parse() {
-        assert_eq!(DocType::try_from("memory").unwrap(), DocType::Memory);
-        assert_eq!(DocType::try_from("daily_log").unwrap(), DocType::DailyLog);
-        assert!(DocType::try_from("invalid").is_err());
+    fn test_normalize_directory() {
+        assert_eq!(normalize_directory("foo/bar/"), "foo/bar");
+        assert_eq!(normalize_directory("foo/bar"), "foo/bar");
+        assert_eq!(normalize_directory("/"), "");
+        assert_eq!(normalize_directory(""), "");
    }
 }
@@ -4,14 +4,14 @@
 //! - Documents in `memory_documents` table
 //! - Chunks in `memory_chunks` table (with FTS and vector indexes)

-use chrono::Utc;
+use chrono::{DateTime, Utc};
 use deadpool_postgres::Pool;
 use pgvector::Vector;
 use uuid::Uuid;

 use crate::error::WorkspaceError;

-use crate::workspace::document::{DocType, MemoryChunk, MemoryDocument};
+use crate::workspace::document::{MemoryChunk, MemoryDocument, WorkspaceEntry};
 use crate::workspace::search::{RankedResult, SearchConfig, SearchResult, reciprocal_rank_fusion};

 /// Database repository for workspace operations.
@@ -37,50 +37,34 @@ impl Repository {

    // ==================== Document Operations ====================

-    /// Get a document by type and optional title.
-    pub async fn get_document(
+    /// Get a document by its path.
+    pub async fn get_document_by_path(
        &self,
        user_id: &str,
        agent_id: Option<Uuid>,
-        doc_type: DocType,
-        title: Option<&str>,
+        path: &str,
    ) -> Result<MemoryDocument, WorkspaceError> {
        let conn = self.conn().await?;

-        let row = if let Some(title) = title {
-            conn.query_opt(
+        let row = conn
+            .query_opt(
                r#"
-                SELECT id, user_id, agent_id, doc_type, title, content,
+                SELECT id, user_id, agent_id, path, content,
                       created_at, updated_at, metadata
                FROM memory_documents
-                WHERE user_id = $1 AND agent_id IS NOT DISTINCT FROM $2
-                  AND doc_type = $3 AND title = $4
+                WHERE user_id = $1 AND agent_id IS NOT DISTINCT FROM $2 AND path = $3
                "#,
-                &[&user_id, &agent_id, &doc_type.as_str(), &title],
+                &[&user_id, &agent_id, &path],
            )
            .await
-        } else {
-            conn.query_opt(
-                r#"
-                SELECT id, user_id, agent_id, doc_type, title, content,
-                       created_at, updated_at, metadata
-                FROM memory_documents
-                WHERE user_id = $1 AND agent_id IS NOT DISTINCT FROM $2
-                  AND doc_type = $3 AND title IS NULL
-                "#,
-                &[&user_id, &agent_id, &doc_type.as_str()],
-            )
-            .await
-        };
-
-        let row = row.map_err(|e| WorkspaceError::SearchFailed {
-            reason: format!("Query failed: {}", e),
-        })?;
+            .map_err(|e| WorkspaceError::SearchFailed {
+                reason: format!("Query failed: {}", e),
+            })?;

        match row {
-            Some(row) => Ok(self.row_to_document(&row)?),
+            Some(row) => Ok(self.row_to_document(&row)),
            None => Err(WorkspaceError::DocumentNotFound {
-                doc_type: doc_type.to_string(),
+                doc_type: path.to_string(),
                user_id: user_id.to_string(),
            }),
        }
@@ -93,7 +77,7 @@ impl Repository {
        let row = conn
            .query_opt(
                r#"
-                SELECT id, user_id, agent_id, doc_type, title, content,
+                SELECT id, user_id, agent_id, path, content,
                       created_at, updated_at, metadata
                FROM memory_documents WHERE id = $1
                "#,
@@ -105,7 +89,7 @@ impl Repository {
            })?;

        match row {
-            Some(row) => Ok(self.row_to_document(&row)?),
+            Some(row) => Ok(self.row_to_document(&row)),
            None => Err(WorkspaceError::DocumentNotFound {
                doc_type: "unknown".to_string(),
                user_id: "unknown".to_string(),
@@ -113,16 +97,15 @@ impl Repository {
        }
    }

-    /// Get or create a document.
-    pub async fn get_or_create_document(
+    /// Get or create a document by path.
+    pub async fn get_or_create_document_by_path(
        &self,
        user_id: &str,
        agent_id: Option<Uuid>,
-        doc_type: DocType,
-        title: Option<&str>,
+        path: &str,
    ) -> Result<MemoryDocument, WorkspaceError> {
        // Try to get existing document first
-        match self.get_document(user_id, agent_id, doc_type, title).await {
+        match self.get_document_by_path(user_id, agent_id, path).await {
            Ok(doc) => return Ok(doc),
            Err(WorkspaceError::DocumentNotFound { .. }) => {}
            Err(e) => return Err(e),
@@ -132,14 +115,15 @@ impl Repository {
        let conn = self.conn().await?;
        let id = Uuid::new_v4();
        let now = Utc::now();
+        let metadata = serde_json::json!({});

        conn.execute(
            r#"
-            INSERT INTO memory_documents (id, user_id, agent_id, doc_type, title, content, created_at, updated_at)
-            VALUES ($1, $2, $3, $4, $5, '', $6, $7)
-            ON CONFLICT (user_id, agent_id, doc_type, title) DO NOTHING
+            INSERT INTO memory_documents (id, user_id, agent_id, path, content, metadata, created_at, updated_at)
+            VALUES ($1, $2, $3, $4, '', $5, $6, $7)
+            ON CONFLICT (user_id, agent_id, path) DO NOTHING
            "#,
-            &[&id, &user_id, &agent_id, &doc_type.as_str(), &title, &now, &now],
+            &[&id, &user_id, &agent_id, &path, &metadata, &now, &now],
        )
        .await
        .map_err(|e| WorkspaceError::SearchFailed {
@@ -147,7 +131,7 @@ impl Repository {
        })?;

        // Fetch the document (might have been created by concurrent request)
-        self.get_document(user_id, agent_id, doc_type, title).await
+        self.get_document_by_path(user_id, agent_id, path).await
    }

    /// Update a document's content.
@@ -166,31 +150,108 @@ impl Repository {
        Ok(())
    }

-    /// List documents by type.
+    /// Delete a document by its path.
+    pub async fn delete_document_by_path(
+        &self,
+        user_id: &str,
+        agent_id: Option<Uuid>,
+        path: &str,
+    ) -> Result<(), WorkspaceError> {
+        let conn = self.conn().await?;
+
+        // First get the document to delete its chunks
+        let doc = self.get_document_by_path(user_id, agent_id, path).await?;
+        self.delete_chunks(doc.id).await?;
+
+        // Delete the document
+        conn.execute(
+            r#"
+            DELETE FROM memory_documents
+            WHERE user_id = $1 AND agent_id IS NOT DISTINCT FROM $2 AND path = $3
+            "#,
+            &[&user_id, &agent_id, &path],
+        )
+        .await
+        .map_err(|e| WorkspaceError::SearchFailed {
+            reason: format!("Delete failed: {}", e),
+        })?;
+
+        Ok(())
+    }
+
+    /// List files and directories in a directory path.
+    ///
+    /// Returns immediate children (not recursive).
+    /// Empty string lists the root directory.
+    pub async fn list_directory(
+        &self,
+        user_id: &str,
+        agent_id: Option<Uuid>,
+        directory: &str,
+    ) -> Result<Vec<WorkspaceEntry>, WorkspaceError> {
+        let conn = self.conn().await?;
+
+        let rows = conn
+            .query(
+                "SELECT path, is_directory, updated_at, content_preview FROM list_workspace_files($1, $2, $3)",
+                &[&user_id, &agent_id, &directory],
+            )
+            .await
+            .map_err(|e| WorkspaceError::SearchFailed {
+                reason: format!("List directory failed: {}", e),
+            })?;
+
+        Ok(rows
+            .iter()
+            .map(|row| {
+                let updated_at: Option<DateTime<Utc>> = row.get("updated_at");
+                WorkspaceEntry {
+                    path: row.get("path"),
+                    is_directory: row.get("is_directory"),
+                    updated_at,
+                    content_preview: row.get("content_preview"),
+                }
+            })
+            .collect())
+    }
+
+    /// List all file paths in the workspace (flat list).
+    pub async fn list_all_paths(
+        &self,
+        user_id: &str,
+        agent_id: Option<Uuid>,
+    ) -> Result<Vec<String>, WorkspaceError> {
+        let conn = self.conn().await?;
+
+        let rows = conn
+            .query(
+                r#"
+                SELECT path FROM memory_documents
+                WHERE user_id = $1 AND agent_id IS NOT DISTINCT FROM $2
+                ORDER BY path
+                "#,
+                &[&user_id, &agent_id],
+            )
+            .await
+            .map_err(|e| WorkspaceError::SearchFailed {
+                reason: format!("List paths failed: {}", e),
+            })?;
+
+        Ok(rows.iter().map(|row| row.get("path")).collect())
+    }
+
+    /// List all documents for a user.
    pub async fn list_documents(
        &self,
        user_id: &str,
        agent_id: Option<Uuid>,
-        doc_type: Option<DocType>,
    ) -> Result<Vec<MemoryDocument>, WorkspaceError> {
        let conn = self.conn().await?;

-        let rows = if let Some(dt) = doc_type {
-            conn.query(
+        let rows = conn
+            .query(
                r#"
-                SELECT id, user_id, agent_id, doc_type, title, content,
-                       created_at, updated_at, metadata
-                FROM memory_documents
-                WHERE user_id = $1 AND agent_id IS NOT DISTINCT FROM $2 AND doc_type = $3
-                ORDER BY updated_at DESC
-                "#,
-                &[&user_id, &agent_id, &dt.as_str()],
-            )
-            .await
-        } else {
-            conn.query(
-                r#"
-                SELECT id, user_id, agent_id, doc_type, title, content,
+                SELECT id, user_id, agent_id, path, content,
                       created_at, updated_at, metadata
                FROM memory_documents
                WHERE user_id = $1 AND agent_id IS NOT DISTINCT FROM $2
@@ -199,30 +260,24 @@ impl Repository {
                &[&user_id, &agent_id],
            )
            .await
-        };
+            .map_err(|e| WorkspaceError::SearchFailed {
+                reason: format!("Query failed: {}", e),
+            })?;

-        let rows = rows.map_err(|e| WorkspaceError::SearchFailed {
-            reason: format!("Query failed: {}", e),
-        })?;
-
-        rows.iter().map(|r| self.row_to_document(r)).collect()
+        Ok(rows.iter().map(|r| self.row_to_document(r)).collect())
    }

-    fn row_to_document(&self, row: &tokio_postgres::Row) -> Result<MemoryDocument, WorkspaceError> {
-        let doc_type_str: String = row.get("doc_type");
-        let doc_type = DocType::try_from(doc_type_str.as_str())?;
-
-        Ok(MemoryDocument {
+    fn row_to_document(&self, row: &tokio_postgres::Row) -> MemoryDocument {
+        MemoryDocument {
            id: row.get("id"),
            user_id: row.get("user_id"),
            agent_id: row.get("agent_id"),
-            doc_type,
-            title: row.get("title"),
+            path: row.get("path"),
            content: row.get("content"),
            created_at: row.get("created_at"),
            updated_at: row.get("updated_at"),
            metadata: row.get("metadata"),
-        })
+        }
    }

    // ==================== Chunk Operations ====================
@@ -374,7 +429,6 @@ impl Repository {
    ) -> Result<Vec<RankedResult>, WorkspaceError> {
        let conn = self.conn().await?;

-        // Use plainto_tsquery for natural language queries
        let rows = conn
            .query(
                r#"
@@ -401,7 +455,7 @@ impl Repository {
                chunk_id: row.get("chunk_id"),
                document_id: row.get("document_id"),
                content: row.get("content"),
-                rank: (i + 1) as u32, // 1-based rank
+                rank: (i + 1) as u32,
            })
            .collect())
    }
@@ -417,7 +471,6 @@ impl Repository {
        let conn = self.conn().await?;
        let embedding_vec = Vector::from(embedding.to_vec());

-        // Use cosine distance (<=>)
        let rows = conn
            .query(
                r#"
@@ -444,7 +497,7 @@ impl Repository {
                chunk_id: row.get("chunk_id"),
                document_id: row.get("document_id"),
                content: row.get("content"),
-                rank: (i + 1) as u32, // 1-based rank
+                rank: (i + 1) as u32,
            })
            .collect())
    }