diff --git a/cortex-mem-cli/README.md b/cortex-mem-cli/README.md index 22810f2..f9e9f94 100644 --- a/cortex-mem-cli/README.md +++ b/cortex-mem-cli/README.md @@ -1,172 +1,225 @@ # Cortex Memory CLI -`cortex-mem-cli` 是 Cortex Memory 系统的命令行界面，提供完整的终端访问功能。作为与系统交互的主要方式之一，它支持会话管理、消息操作、搜索和记忆提取等核心功能。 +`cortex-mem-cli` is the command-line interface for the Cortex Memory system, providing complete terminal access to memory management functionality. -## ✨ 功能特性 +## ✨ Features -- 🗣️ **会话管理**: 创建、列出、关闭会话 -- 💬 **消息操作**: 添加、搜索、删除消息 -- 🔍 **智能搜索**: 支持时间范围和维度过滤 -- 🧠 **记忆提取**: 自动提取事实、决策和实体 -- 📊 **统计信息**: 查看系统状态和使用统计 -- 🎨 **友好输出**: 彩色终端输出，可配置详细级别 +- 🗣️ **Session Management**: Create and list sessions +- 💬 **Message Operations**: Add, search, get, and delete messages +- 🔍 **Semantic Search**: Vector-based search with scope filtering +- 📊 **Layer Management**: Generate and manage L0/L1 layer files +- 📈 **Statistics**: View system status and usage statistics +- 🎨 **Friendly Output**: Colored terminal output with configurable verbosity -## 🚀 快速开始 +## 🚀 Quick Start -### 安装 +### Installation ```bash -# 从源码构建 +# Build from source cd cortex-mem cargo build --release --bin cortex-mem -# 或直接运行 +# Or run directly cargo run --bin cortex-mem -- --help ``` -### 基本使用 +### Basic Usage ```bash -# 创建新会话 -./cortex-mem session create tech-discussion --title "技术讨论" +# Create a new session +./cortex-mem session create tech-discussion --title "Technical Discussion" -# 添加消息 -./cortex-mem add --thread tech-discussion "如何实现OAuth认证？" +# Add a message +./cortex-mem add --thread tech-discussion "How to implement OAuth authentication?" -# 搜索相关内容 +# Search for relevant content ./cortex-mem search "OAuth" --thread tech-discussion -# 提取记忆 -./cortex-mem session extract tech-discussion - -# 查看统计 +# View statistics ./cortex-mem stats ``` -## 📖 详细命令参考 - -### 会话管理命令 - -#### 创建会话 - -```bash -cortex-mem session create [--title ] - -# 示例 -cortex-mem session create project-planning --title "项目规划讨论" -cortex-mem session create 2024-01-15-review # 无标题 -``` +## 📖 Command Reference -#### 关闭会话 +### Global Options -```bash -cortex-mem session close <thread-id> +| Option | Short | Default | Description | +|--------|-------|---------|-------------| +| `--config` | `-c` | `config.toml` | Path to configuration file | +| `--tenant` | | `default` | Tenant identifier for memory isolation | +| `--verbose` | `-v` | false | Enable verbose/debug logging | -# 示例 -cortex-mem session close tech-discussion -``` +### Session Commands -#### 提取记忆 +#### Create Session ```bash -cortex-mem session extract <thread-id> +cortex-mem session create <thread-id> [--title <title>] -# 示例 -cortex-mem session extract project-planning +# Examples +cortex-mem session create project-planning --title "Project Planning Discussion" +cortex-mem session create 2024-01-15-review # Without title ``` -#### 列出所有会话 +#### List Sessions ```bash cortex-mem session list ``` -### 消息操作命令 +Output displays: thread_id, status, created_at, updated_at + +### Message Commands -#### 添加消息 +#### Add Message ```bash cortex-mem add --thread <thread-id> [--role <role>] <content> -# 角色选项: user, assistant, system (默认: user) -cortex-mem add --thread tech-support --role user "忘记密码了怎么办？" -cortex-mem add --thread tech-support --role assistant "请访问重置密码页面..." +# Role options: user, assistant, system (default: user) +cortex-mem add --thread tech-support --role user "I forgot my password, what should I do?" +cortex-mem add --thread tech-support --role assistant "Please visit the password reset page..." ``` -#### 搜索消息 +| Argument | Short | Default | Description | +|----------|-------|---------|-------------| +| `--thread` | `-t` | (required) | Thread ID for the message | +| `--role` | `-r` | `user` | Message role: `user`, `assistant`, or `system` | +| `content` | | (required) | Message content text | + +#### Search Messages ```bash -cortex-mem search <query> [--thread <thread-id>] [-n <limit>] [-s <min-score>] +cortex-mem search <query> [--thread <thread-id>] [-n <limit>] [-s <min-score>] [--scope <scope>] -# 示例 -cortex-mem search "密码" +# Examples +cortex-mem search "password" cortex-mem search "OAUTH" -n 5 -s 0.7 cortex-mem search "API" --thread tech-support ``` -#### 列出消息 +| Argument | Short | Default | Description | +|----------|-------|---------|-------------| +| `query` | | (required) | Search query text | +| `--thread` | `-t` | None | Thread ID to search within | +| `--limit` | `-n` | `10` | Maximum number of results | +| `--min-score` | `-s` | `0.4` | Minimum relevance score (0.0-1.0) | +| `--scope` | | `session` | Search scope: `session`, `user`, or `agent` | + +#### List Memories ```bash -cortex-mem list [--thread <thread-id>] [--dimension <dimension>] +cortex-mem list [--uri <uri>] [--include-abstracts] -# 示例 +# Examples cortex-mem list -cortex-mem list --thread tech-support -cortex-mem list --dimension agent +cortex-mem list --uri cortex://user +cortex-mem list --include-abstracts ``` -#### 获取特定消息 +| Argument | Short | Default | Description | +|----------|-------|---------|-------------| +| `--uri` | `-u` | `cortex://session` | URI path to list | +| `--include-abstracts` | | false | Show L0 abstracts in results | + +#### Get Memory ```bash -cortex-mem get <uri> +cortex-mem get <uri> [--abstract-only] -# 示例 +# Examples cortex-mem get cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md +cortex-mem get cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md --abstract-only ``` -#### 删除消息 +| Argument | Short | Default | Description | +|----------|-------|---------|-------------| +| `uri` | | (required) | Memory URI to retrieve | +| `--abstract-only` | `-a` | false | Show L0 abstract instead of full content | + +#### Delete Memory ```bash cortex-mem delete <uri> + +# Example +cortex-mem delete cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md ``` -### 系统命令 +### Layer Commands + +#### Ensure All Layers -#### 查看统计信息 +Generate missing `.abstract.md` (L0) and `.overview.md` (L1) files for all memories. ```bash -cortex-mem stats +cortex-mem layers ensure-all ``` -## ⚙️ 配置选项 - -### 数据目录 +#### Layer Status -默认数据目录为 `./cortex-data`，可通过 `--data-dir` 参数自定义： +Show L0/L1 file coverage status. ```bash -cortex-mem --data-dir /path/to/data session list +cortex-mem layers status ``` -### 详细输出 +#### Regenerate Oversized Abstracts -使用 `--verbose` 或 `-v` 参数启用详细日志： +Regenerate `.abstract.md` files exceeding the size limit. ```bash -cortex-mem --verbose add --thread test "Hello" +cortex-mem layers regenerate-oversized ``` -### 配置文件 +### Statistics -CLI遵循以下配置优先级： -1. 命令行参数 -2. 环境变量 -3. 配置文件 (config.toml) -4. 默认值 +```bash +cortex-mem stats +``` + +Displays: +- Number of sessions +- Number of user memories +- Number of agent memories +- Total message count +- Data directory path + +## ⚙️ Configuration + +### Configuration File + +Create a `config.toml` file with the following structure: + +```toml +[cortex] +data_dir = "/path/to/cortex-data" # Optional, has smart defaults + +[llm] +api_base_url = "https://api.openai.com/v1" +api_key = "your-api-key" +model_efficient = "gpt-4o-mini" +temperature = 0.7 +max_tokens = 4096 + +[embedding] +api_base_url = "https://api.openai.com/v1" +api_key = "your-embedding-api-key" +model_name = "text-embedding-3-small" +batch_size = 10 +timeout_secs = 30 + +[qdrant] +url = "http://localhost:6333" +collection_name = "cortex-mem" +embedding_dim = 1536 +timeout_secs = 30 +``` -## 🌐 环境变量 +### Environment Variables -可以通过环境变量覆盖配置： +Configuration can be overridden via environment variables: ```bash export CORTEX_DATA_DIR="/custom/path" @@ -176,124 +229,105 @@ export QDRANT_URL="http://localhost:6333" cortex-mem session create test ``` -## 📝 完整工作流示例 +### Data Directory Resolution -```bash -# 1. 创建会话 -cortex-mem session create customer-support --title "客户支持会话" - -# 2. 添加对话 -cortex-mem add --thread customer-support "我的订单状态是什么？" -cortex-mem add --thread customer-support --role assistant "让我帮您查询订单状态..." - -# 3. 搜索相关信息 -cortex-mem search "订单" --thread customer-support +The data directory is resolved in the following priority order: +1. `cortex.data_dir` config value +2. `CORTEX_DATA_DIR` environment variable +3. System app data directory (e.g., `%APPDATA%/tars/cortex` on Windows) +4. Fallback: `./.cortex` in current directory -# 4. 提取记忆到用户档案 -cortex-mem session extract customer-support +## 📝 Complete Workflow Example -# 5. 查看提取的记忆 -cortex-mem list --dimension user +```bash +# 1. Create a session +cortex-mem session create customer-support --title "Customer Support Session" -# 6. 关闭会话 -cortex-mem session close customer-support +# 2. Add conversation messages +cortex-mem add --thread customer-support "What's my order status?" +cortex-mem add --thread customer-support --role assistant "Let me check your order status..." -# 7. 查看系统统计 -cortex-mem stats -``` +# 3. Search for relevant information +cortex-mem search "order" --thread customer-support -## 🎨 输出格式 +# 4. View extracted memories +cortex-mem list --uri cortex://user -CLI使用颜色编码以提高可读性： +# 5. Get a specific memory with abstract +cortex-mem get cortex://session/customer-support/timeline/... --abstract-only -- 🔵 **蓝色**: 会话ID和文件URI -- 🟢 **绿色**: 成功操作 -- 🟡 **黄色**: 警告信息 -- 🔴 **红色**: 错误信息 -- ⚪ **白色**: 一般信息 +# 6. View system statistics +cortex-mem stats -## 🧪 脚本测试 +# 7. Generate missing layer files +cortex-mem layers ensure-all +``` -项目包含测试脚本用于快速验证功能： +## 🎨 Output Format -```bash -# 快速测试 -./cortex-mem-cli/quick-test.sh +CLI uses color coding for better readability: -# 完整演示 -./cortex-mem-cli/demo.sh -``` +- 🔵 **Blue**: Session IDs and file URIs +- 🟢 **Green**: Successful operations +- 🟡 **Yellow**: Warning messages +- 🔴 **Red**: Error messages +- ⚪ **White**: General information -## 🔍 故障排除 +## 🔍 Troubleshooting -### 常见问题 +### Common Issues -**数据目录权限错误** +**Data directory permission error** ```bash chmod 755 ./cortex-data ``` -**LLM服务不可用** +**LLM service unavailable** ```bash export LLM_API_BASE_URL="https://api.openai.com/v1" export LLM_API_KEY="your-key" -export LLM_MODEL="gpt-4" ``` -**向量搜索失败** +**Vector search failure** ```bash -# 启动Qdrant +# Start Qdrant docker run -p 6333:6333 qdrant/qdrant -# 配置连接 +# Configure connection export QDRANT_URL="http://localhost:6333" ``` -### 调试模式 +### Debug Mode ```bash -# 启用详细日志查看调试信息 -cortex-mem --verbose --log-level debug session create debug-test +# Enable verbose logging +cortex-mem --verbose session create debug-test -# 查看完整错误堆栈 +# View full error stack trace RUST_BACKTRACE=1 cortex-mem search "test" ``` -## 🛣️ 路线图 +## 📚 Related Resources -计划中的功能： +- [Cortex Memory Main Project](../README.md) +- [Core Library Documentation](../cortex-mem-core/README.md) +- [HTTP API Service](../cortex-mem-service/README.md) +- [Architecture Overview](../../litho.docs/en/2.Architecture.md) -- [ ] 批量操作命令 -- [ ] 交互式模式 -- [ ] 配置管理命令 -- [ ] 导入/导出工具 -- [ ] 自动补全支持 -- [ ] 插件系统 +## 🤝 Contributing -## 📚 更多资源 +Contributions are welcome! Please follow these steps: -- [Cortex Memory 主项目](../README.md) -- [核心库文档](../cortex-mem-core/README.md) -- [HTTP API服务](../cortex-mem-service/README.md) -- [架构概述](../../litho.docs/en/2.Architecture.md) +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Create a Pull Request -## 🤝 贡献 +## 📄 License -欢迎贡献！请遵循以下步骤： - -1. Fork 项目仓库 -2. 创建功能分支 (`git checkout -b feature/amazing-feature`) -3. 提交更改 (`git commit -m 'Add amazing feature'`) -4. 推送到分支 (`git push origin feature/amazing-feature`) -5. 创建 Pull Request - -## 📄 许可证 - -MIT 许可证 - 详见 [LICENSE](../../LICENSE) 文件 +MIT License - see the [LICENSE](../../LICENSE) file for details. --- -**Built with ❤️ using Rust and the Cortex Memory Core** -``` - -接下来，我将继续为其他子crate创建或更新README文件。 +**Built with ❤️ using Rust and the Cortex Memory Core** \ No newline at end of file diff --git a/cortex-mem-cli/demo.sh b/cortex-mem-cli/demo.sh deleted file mode 100755 index d867b5d..0000000 --- a/cortex-mem-cli/demo.sh +++ /dev/null @@ -1,55 +0,0 @@ -#!/bin/bash -# Cortex-Mem CLI 简洁测试脚本（无警告） - -set -e - -echo "================================" -echo "Cortex-Mem CLI 快速测试" -echo "================================" -echo "" - -# 使用 --quiet 去掉编译输出，2>&1 | grep -v "warning:" 去掉警告 -CM="cargo run --quiet --bin cortex-mem --" - -echo "📊 Step 1: 查看初始统计..." -$CM stats -echo "" - -echo "📝 Step 2: 创建测试会话..." -$CM session create demo-session --title "演示会话" -echo "" - -echo "✉️ Step 3: 添加测试消息..." -$CM add --thread demo-session "你好，我想了解如何使用Rust实现OAuth 2.0" -$CM add --thread demo-session --role assistant "我建议使用oauth2 crate，这是Rust生态中最成熟的OAuth实现" -$CM add --thread demo-session "具体的集成步骤是什么？" -$CM add --thread demo-session --role assistant "首先需要配置OAuth客户端，然后实现授权流程和token管理" -echo "" - -echo "📋 Step 4: 列出会话内容..." -$CM list --thread demo-session -echo "" - -echo "🔍 Step 5: 搜索测试..." -$CM search "OAuth Rust" --thread demo-session -n 5 -echo "" - -echo "📋 Step 6: 查看所有会话..." -$CM session list -echo "" - -echo "📊 Step 7: 查看统计..." -$CM stats -echo "" - -echo "================================" -echo "✅ 测试完成！" -echo "================================" -echo "" -echo "💡 提示：" -echo " - 数据保存在: ./cortex-data/" -echo " - 查看文件: ls -la cortex-data/threads/demo-session/" -echo " - 查看消息: $CM get <URI>" -echo " - 提取记忆: $CM session extract demo-session" -echo " - 关闭会话: $CM session close demo-session" -echo "" diff --git a/cortex-mem-cli/quick-test.sh b/cortex-mem-cli/quick-test.sh deleted file mode 100755 index 1c5dec2..0000000 --- a/cortex-mem-cli/quick-test.sh +++ /dev/null @@ -1,59 +0,0 @@ -#!/bin/bash -# Cortex-Mem CLI 快速测试脚本 - -set -e - -echo "================================" -echo "Cortex-Mem CLI 快速测试" -echo "================================" -echo "" - -# 设置别名以简化命令 -alias cm='cargo run --quiet --bin cortex-mem --' - -echo "📊 Step 1: 查看初始统计..." -cm stats -echo "" - -echo "📝 Step 2: 创建测试会话..." -cm session create test-session --title "CLI测试会话" -echo "" - -echo "✉️ Step 3: 添加测试消息..." -cm add --thread test-session "这是第一条测试消息" -cm add --thread test-session --role assistant "收到，这是助手的回复" -cm add --thread test-session "我们来讨论一下OAuth 2.0的实现" -cm add --thread test-session --role assistant "好的，OAuth 2.0建议使用授权码流程" -echo "" - -echo "📋 Step 4: 列出会话内容..." -cm list --thread test-session -echo "" - -echo "🔍 Step 5: 搜索测试..." -cm search "OAuth" --thread test-session -n 5 -echo "" - -echo "📋 Step 6: 查看所有会话..." -cm session list -echo "" - -echo "🧠 Step 7: 提取记忆（注意：当前使用placeholder）..." -cm session extract test-session -echo "" - -echo "🔒 Step 8: 关闭会话..." -cm session close test-session -echo "" - -echo "📊 Step 9: 查看最终统计..." -cm stats -echo "" - -echo "================================" -echo "✅ 测试完成！" -echo "================================" -echo "" -echo "数据已保存到: ./cortex-data/" -echo "查看文件结构: tree cortex-data/" -echo "" diff --git a/cortex-mem-core/README.md b/cortex-mem-core/README.md index dc3437b..6a97a67 100644 --- a/cortex-mem-core/README.md +++ b/cortex-mem-core/README.md @@ -1,4 +1,4 @@ -# Cortex Memory Core Core Library +# Cortex Memory Core Library `cortex-mem-core` is the foundational library of the Cortex Memory system, providing core services and abstractions for AI agent memory management. @@ -6,10 +6,10 @@ Cortex Memory Core implements: - A virtual filesystem with `cortex://` URI scheme for memory storage -- Three-tier memory architecture (L0/L1/L3 layers) +- Three-tier memory architecture (L0/L1/L2 layers) - Session-based conversational memory management - Vector search integration with Qdrant -- Automated memory extraction and profiling +- LLM-based memory extraction and profiling - Event-driven automation system ## 🏗️ Architecture @@ -19,18 +19,55 @@ Cortex Memory Core implements: | Module | Purpose | Key Components | |--------|---------|----------------| | **`filesystem`** | Virtual file system with custom URI scheme | `CortexFilesystem`, `CortexUri`, `FilesystemOperations` | -| **`session`** | Conversational session management | `SessionManager`, `Message`, `TimelineGenerator` | -| **`vector_store`** | Vector database abstraction | `VectorStore`, embedding integration | -| **`search`** | Semantic and hybrid search engines | `VectorSearchEngine`, `SearchOptions` | +| **`session`** | Conversational session management | `SessionManager`, `Message`, `TimelineGenerator`, `ParticipantManager` | +| **`vector_store`** | Vector database abstraction | `VectorStore` trait, `QdrantVectorStore` | +| **`search`** | Semantic and layered search engines | `VectorSearchEngine`, `SearchOptions`, `SearchResult` | | **`extraction`** | Memory extraction and profiling | `MemoryExtractor`, `ExtractedMemories` | -| **`automation`** | Event-driven automation | `AutomationManager`, `CortexEvent` | -| **`layers`** | Three-tier memory architecture | `ContextLayer`, layer management | -| **`llm`** | Large language model abstraction | `LlmClient`, LLM providers | -| **`events`** | Event system for automation | `CortexEvent`, event handling | +| **`automation`** | Event-driven automation | `AutomationManager`, `AutoIndexer`, `AutoExtractor`, `LayerGenerator` | +| **`layers`** | Three-tier memory architecture | `LayerManager`, `ContextLayer` | +| **`llm`** | Large language model abstraction | `LLMClient` trait, `LLMClientImpl` | +| **`embedding`** | Embedding generation | `EmbeddingClient`, `EmbeddingCache` | +| **`events`** | Event system for automation | `CortexEvent`, `EventBus` | +| **`builder`** | Unified initialization API | `CortexMemBuilder`, `CortexMem` | ## 🚀 Quick Start -### Basic Usage +### Using CortexMemBuilder (Recommended) + +```rust +use cortex_mem_core::{CortexMemBuilder, LLMConfig, QdrantConfig, EmbeddingConfig}; +use std::sync::Arc; + +#[tokio::main] +async fn main() -> Result<(), Box<dyn std::error::Error>> { + let cortex = CortexMemBuilder::new("./cortex-data") + .with_embedding(EmbeddingConfig { + api_base_url: "https://api.openai.com/v1".to_string(), + api_key: "your-api-key".to_string(), + model_name: "text-embedding-3-small".to_string(), + batch_size: 10, + timeout_secs: 30, + }) + .with_qdrant(QdrantConfig { + url: "http://localhost:6333".to_string(), + collection_name: "cortex_memories".to_string(), + embedding_dim: 1536, + timeout_secs: 30, + tenant_id: "default".to_string(), + }) + .build() + .await?; + + // Access components + let session_manager = cortex.session_manager(); + let filesystem = cortex.filesystem(); + let vector_store = cortex.vector_store(); + + Ok(()) +} +``` + +### Basic Filesystem Usage ```rust use cortex_mem_core::{CortexFilesystem, FilesystemOperations}; @@ -50,6 +87,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> { let content = fs.read("cortex://user/john/preferences.md").await?; println!("Content: {}", content); + // List directory + let entries = fs.list("cortex://user/john").await?; + for entry in entries { + println!("{}: {} ({})", entry.name, entry.uri, + if entry.is_directory { "dir" } else { "file" }); + } + Ok(()) } ``` @@ -57,7 +101,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> { ### Session Management ```rust -use cortex_mem_core::{SessionManager, SessionConfig, Message, MessageRole}; +use cortex_mem_core::{SessionManager, SessionConfig, Message, MessageRole, CortexFilesystem}; use std::sync::Arc; #[tokio::main] @@ -65,27 +109,23 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> { let fs = Arc::new(CortexFilesystem::new("./cortex-data")?); fs.initialize().await?; - let session_manager = SessionManager::new(fs); + let session_manager = SessionManager::new(fs, SessionConfig::default()); // Create a session - let session = session_manager.create_session( - "tech-support", - Some("Technical Support Chat".to_string()) - ).await?; + let session = session_manager.create_session("tech-support").await?; // Add messages session_manager.add_message( &session.thread_id, - Message { - role: MessageRole::User, - content: "How do I reset my password?".to_string(), - metadata: Default::default(), - } + "user", + "How do I reset my password?" ).await?; - // Extract memories - let memories = session_manager.extract_memories(&session.thread_id).await?; - println!("Extracted {} facts", memories.facts.len()); + // List sessions + let sessions = session_manager.list_sessions().await?; + for s in sessions { + println!("Session: {} ({:?})", s.thread_id, s.status); + } Ok(()) } @@ -99,19 +139,31 @@ use std::sync::Arc; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { - let fs = Arc::new(CortexFilesystem::new("./cortex-data")?); - fs.initialize().await?; + let search_engine = VectorSearchEngine::new( + qdrant_store, + embedding_client, + filesystem + ); - let search_engine = VectorSearchEngine::new(fs, vec![])?; + // Basic semantic search + let results = search_engine.semantic_search( + "password reset", + SearchOptions { + limit: 10, + threshold: 0.5, + root_uri: Some("cortex://session".to_string()), + recursive: true, + } + ).await?; - // Search with options - let results = search_engine.search( + // Layered semantic search (L0 -> L1 -> L2) + let layered_results = search_engine.layered_semantic_search( "password reset", SearchOptions::default() ).await?; - for result in results { - println!("Found: {} (score: {:.2})", result.content, result.score); + for result in layered_results { + println!("Found: {} (score: {:.2})", result.uri, result.score); } Ok(()) @@ -125,56 +177,224 @@ The Cortex Filesystem extends standard file operations with custom URIs: ### URI Scheme ``` -cortex://{dimension}/{tenant}/{path/to/resource} +cortex://{dimension}/{category}/{subcategory}/{resource} ``` -#### Dimensions: -- **`users`** - User-specific memories -- **`agents`** - Agent-specific memories -- **`threads`** - Conversational sessions -- **`global`** - Shared resources and knowledge +### Dimensions and Categories + +| Dimension | Categories | Description | +|-----------|------------|-------------| +| **`session`** | `{session-id}/timeline` | Conversational sessions with timeline | +| **`user`** | `preferences`, `entities`, `events` | User-specific memories | +| **`agent`** | `cases`, `skills`, `instructions` | Agent-specific memories | +| **`resources`** | Various | Shared resources | ### Example URIs ``` +cortex://session/tech-support/timeline/2024/01/15/14_30_00_abc123.md cortex://user/john/preferences.md -cortex://agent/tech-support/knowledge.md -cortex://session/session-123/timeline/2024/01/15/14_30_00_abc123.md -cortex://global/company-policy.md +cortex://agent/assistant/skills/rust-programming.md +cortex://resources/templates/meeting-notes.md ``` -## 📚 Memory Architecture +## 📚 Memory Architecture (Three-Tier System) Cortex implements a three-tier memory system: -### L0: Abstract Layer (~100 tokens) -- Ultra-condensed summaries -- Key fact extraction -- Perfect for quick context +| Layer | Size | Purpose | File Suffix | +|-------|------|---------|-------------| +| **L0 Abstract** | ~100 tokens | Ultra-condensed summaries, quick relevance check | `.abstract.md` | +| **L1 Overview** | ~500-2000 tokens | Detailed summaries, key points and decisions | `.overview.md` | +| **L2 Detail** | Full content | Complete original content, source of truth | `.md` (original) | + +### Layer Generation + +```rust +use cortex_mem_core::layers::LayerManager; -### L1: Overview Layer (~500-2000 tokens) -- Detailed summaries -- Key points and decisions -- Good for partial context +let layer_manager = LayerManager::new(filesystem, llm_client); -### L3: Full Content -- Complete original content -- Source of truth -- Used for deep analysis +// Generate all layers for content +let layers = layer_manager.generate_all_layers("cortex://session/.../message.md", &content).await?; + +// Load specific layer +let abstract_content = layer_manager.load("cortex://session/.../message.md", ContextLayer::L0Abstract).await?; +``` + +## 📖 API Reference + +### Core Types + +```rust +// Dimension enum +pub enum Dimension { + Resources, + User, + Agent, + Session, +} + +// Context layers +pub enum ContextLayer { + L0Abstract, // ~100 tokens + L1Overview, // ~500-2000 tokens + L2Detail, // Full content +} + +// Memory types +pub enum MemoryType { + Conversational, + Procedural, + Semantic, + Episodic, +} + +// User memory categories +pub enum UserMemoryCategory { + Profile, + Preferences, + Entities, + Events, +} + +// Agent memory categories +pub enum AgentMemoryCategory { + Cases, + Skills, + Instructions, +} + +// File entry +pub struct FileEntry { + pub uri: String, + pub name: String, + pub is_directory: bool, + pub size: Option<u64>, + pub modified: Option<DateTime<Utc>>, +} + +// Memory with embedding +pub struct Memory { + pub id: String, + pub content: String, + pub embedding: Option<Vec<f32>>, + pub created_at: DateTime<Utc>, + pub updated_at: DateTime<Utc>, + pub metadata: MemoryMetadata, +} + +// Search result +pub struct ScoredMemory { + pub memory: Memory, + pub score: f32, +} +``` + +### FilesystemOperations Trait + +```rust +#[async_trait] +pub trait FilesystemOperations: Send + Sync { + async fn list(&self, uri: &str) -> Result<Vec<FileEntry>>; + async fn read(&self, uri: &str) -> Result<String>; + async fn write(&self, uri: &str, content: &str) -> Result<()>; + async fn delete(&self, uri: &str) -> Result<()>; + async fn exists(&self, uri: &str) -> Result<bool>; + async fn metadata(&self, uri: &str) -> Result<FileMetadata>; +} +``` + +### VectorStore Trait + +```rust +#[async_trait] +pub trait VectorStore: Send + Sync + DynClone { + async fn insert(&self, memory: &Memory) -> Result<()>; + async fn search(&self, query_vector: &[f32], filters: &Filters, limit: usize) -> Result<Vec<ScoredMemory>>; + async fn search_with_threshold(&self, query_vector: &[f32], filters: &Filters, limit: usize, score_threshold: f32) -> Result<Vec<ScoredMemory>>; + async fn update(&self, memory: &Memory) -> Result<()>; + async fn delete(&self, id: &str) -> Result<()>; + async fn get(&self, id: &str) -> Result<Option<Memory>>; + async fn list(&self, filters: &Filters, limit: Option<usize>) -> Result<Vec<Memory>>; + async fn health_check(&self) -> Result<bool>; +} +``` + +### LLMClient Trait + +```rust +#[async_trait] +pub trait LLMClient: Send + Sync { + async fn complete(&self, prompt: &str) -> Result<String>; + async fn complete_with_system(&self, system: &str, prompt: &str) -> Result<String>; + async fn extract_memories(&self, prompt: &str) -> Result<MemoryExtractionResponse>; + async fn extract_structured_facts(&self, prompt: &str) -> Result<StructuredFactExtraction>; + async fn extract_detailed_facts(&self, prompt: &str) -> Result<DetailedFactExtraction>; + fn model_name(&self) -> &str; + fn config(&self) -> &LLMConfig; +} +``` ## 🔧 Configuration +### QdrantConfig + +```rust +pub struct QdrantConfig { + pub url: String, // Default: "http://localhost:6333" + pub collection_name: String, // Default: "cortex_memories" + pub embedding_dim: usize, // Default: 1536 + pub timeout_secs: u64, // Default: 30 + pub tenant_id: String, // Default: "default" +} +``` + +### EmbeddingConfig + +```rust +pub struct EmbeddingConfig { + pub api_base_url: String, // Default: OpenAI API + pub api_key: String, // From EMBEDDING_API_KEY or LLM_API_KEY + pub model_name: String, // Default: "text-embedding-3-small" + pub batch_size: usize, // Default: 10 + pub timeout_secs: u64, // Default: 30 +} +``` + +### LLMConfig + ```rust -use cortex_mem_core::{CortexFilesystem, config::Config}; +pub struct LLMConfig { + pub api_base_url: String, // Default: OpenAI API + pub api_key: String, // From LLM_API_KEY env var + pub model_efficient: String, // Default: "gpt-3.5-turbo" + pub temperature: f32, // Default: 0.1 + pub max_tokens: usize, // Default: 4096 +} +``` + +### SessionConfig -// From environment -let config = Config::from_env()?; +```rust +pub struct SessionConfig { + pub auto_extract_on_close: bool, // Default: true + pub max_messages_per_session: Option<usize>, + pub auto_archive_after_days: Option<i64>, +} +``` -// From file -let config = Config::from_file("config.toml")?; +### AutomationConfig -// Custom configuration -let fs = CortexFilesystem::with_config(config)?; +```rust +pub struct AutomationConfig { + pub auto_index: bool, // Default: true + pub auto_extract: bool, // Default: true + pub index_on_message: bool, // Default: false + pub index_on_close: bool, // Default: true + pub index_batch_delay: u64, // Default: 2 seconds + pub auto_generate_layers_on_startup: bool, // Default: false +} ``` ## 🔄 Event System @@ -182,27 +402,54 @@ let fs = CortexFilesystem::with_config(config)?; Cortex includes an event-driven automation system: ```rust -use cortex_mem_core::{CortexEvent, AutomationManager}; +use cortex_mem_core::{CortexEvent, EventBus, AutomationManager}; + +// Create event bus +let (event_tx, event_rx) = EventBus::new(); -// Handle events +// Publish events +event_tx.publish(CortexEvent::Session(SessionEvent::MessageAdded { + thread_id: "tech-support".to_string(), + message_id: "msg-123".to_string(), +})); + +// Handle events in automation manager match event { - CortexEvent::FilesystemEvent(event) => { - // File changed - trigger re-indexing - } - CortexEvent::SessionEvent(event) => { - // Session updated - trigger extraction + CortexEvent::Session(event) => { + // Session event - trigger extraction/indexing } - CortexEvent::SystemEvent(event) => { - // System event - handle accordingly + CortexEvent::Filesystem(event) => { + // File changed - trigger re-indexing } } ``` +### Event Types + +```rust +pub enum CortexEvent { + Session(SessionEvent), + Filesystem(FilesystemEvent), +} + +pub enum SessionEvent { + Created { thread_id: String }, + MessageAdded { thread_id: String, message_id: String }, + Closed { thread_id: String }, +} + +pub enum FilesystemEvent { + FileCreated { uri: String }, + FileModified { uri: String }, + FileDeleted { uri: String }, +} +``` + ## 🔗 Integration with Other Crates -- **`cortex-mem-config`**: Provides configuration types -- **`cortex-mem-tools`**: Utilities and helpers -- **`cortex-mem-rig`**: RIG framework adapters +- **`cortex-mem-config`**: Configuration loading and management +- **`cortex-mem-tools`**: High-level utilities and MCP tool definitions +- **`cortex-mem-rig`**: Rig framework adapters - **`cortex-mem-service`**: REST API implementation - **`cortex-mem-cli`**: Command-line interface - **`cortex-mem-mcp`**: MCP server implementation @@ -216,17 +463,10 @@ Running tests requires all features: cargo test -p cortex-mem-core --all-features ``` -## 🌟 Features - -- **vector-search**: Enable Qdrant vector database integration (enabled by default) -- **embeddings**: Enable embedding generation -- **automation**: Enable event-driven automation -- **extraction**: Enable LLM-based memory extraction - -## 📝 Dependencies +## 📦 Dependencies Key dependencies include: -- `serde` for serialization +- `serde` / `serde_json` for serialization - `tokio` for async runtime - `qdrant-client` for vector storage - `rig-core` for LLM integration @@ -234,6 +474,8 @@ Key dependencies include: - `uuid` for unique identifiers - `regex` for text matching - `sha2` for hashing +- `tracing` for logging +- `reqwest` for HTTP requests ## 📄 License @@ -247,4 +489,4 @@ Please read our contributing guidelines and submit pull requests to the main rep - [Architecture Overview](../../litho.docs/en/2.Architecture.md) - [Core Workflow](../../litho.docs/en/3.Workflow.md) -- [API Reference](docs/api-reference.md) +- [System Boundaries](../../litho.docs/en/5.Boundary-Interfaces.md) \ No newline at end of file diff --git a/cortex-mem-insights/README.md b/cortex-mem-insights/README.md index 6ddcf40..46666b2 100644 --- a/cortex-mem-insights/README.md +++ b/cortex-mem-insights/README.md @@ -1,150 +1,226 @@ -# Cortex Memory Insights - 可观测性仪表板 +# Cortex Memory Insights - Observability Dashboard -`cortex-mem-insights` 是一个基于 Svelte 构建的 Web 仪表板，提供对 Cortex Memory 系统的可视化监控和管理界面。 +`cortex-mem-insights` is a web-based dashboard built with Svelte 5 that provides visual monitoring and management of the Cortex Memory system. -## 🌟 功能特性 +## 🌟 Features -### 📊 系统仪表板 -- 📈 **实时监控**: 实时显示系统状态、会话数量、消息计数等关键指标 -- 📉 **性能图表**: 可视化搜索性能、提取速度、响应时间等关键性能指标 -- 🔍 **系统健康**: 监控 LLM 服务、向量数据库、文件系统等依赖组件的健康状态 +### 📊 Dashboard +- **Tenants Overview**: View all tenants with statistics (user memories, sessions, agents, resources, files, storage) +- **Service Status**: Monitor health status, version, and LLM availability +- **Storage Card**: Display total size and file counts by category -### 💾 记忆管理 -- 📂 **浏览结构**: 直观浏览 Cortex 文件系统结构，包括用户、代理、会话和资源维度 -- 📝 **查看内容**: 分层查看记忆内容（L0 抽象、L1 概览、L3 完整内容） -- 🏷️ **标签管理**: 查看和管理记忆标签、分类和重要程度 +### 💾 Memory Browser +- **File Browser**: Two-panel layout with file tree and content preview +- **Directory Navigation**: Tabs for User/Session/Agent/Resources roots +- **File Operations**: View, edit, and save memory files +- **Markdown Rendering**: Basic markdown-to-HTML conversion for content preview -### 🔍 智能搜索 -- 🎯 **高级搜索**: 支持多维度、时间范围、标签过滤的高级搜索功能 -- 📊 **结果可视化**: 搜索结果以卡片、列表或时间轴形式展示 -- 💾 **搜索历史**: 保存和管理搜索历史，支持收藏常用查询 +### 🔍 Vector Search +- **Search Form**: Keyword input with scope selector and limit control +- **Scopes**: All, User, Session, Agent +- **Results Display**: Cards showing URI, relevance score, snippet, and expandable full content -### 📱 响应式设计 -- 🖥️ **桌面适配**: 优化的桌面端体验，支持宽屏显示 -- 📱 **移动友好**: 响应式布局，适配平板和手机设备 -- 🌙 **主题切换**: 支持明暗主题自动切换 +### 📱 Responsive Design +- **Desktop Optimized**: Optimized desktop experience with wide screen support +- **Mobile Friendly**: Responsive layout for tablet and mobile devices -## 🚀 快速开始 +## 🚀 Quick Start -### 开发环境要求 +### Prerequisites -- Node.js 18+ 或 Bun -- 现代浏览器（Chrome 90+, Firefox 88+, Safari 14+） +- Node.js 18+ or Bun +- Modern browser (Chrome 90+, Firefox 88+, Safari 14+) +- Cortex Memory Service running on port 8085 -### 安装与运行 +### Installation ```bash -# 进入目录 +# Navigate to directory cd cortex-mem/cortex-mem-insights -# 安装依赖 -bun install # 或 npm install +# Install dependencies +bun install # or npm install -# 启动开发服务器 -bun run dev # 或 npm run dev +# Start development server +bun run dev # or npm run dev -# 构建生产版本 -bun run build # 或 npm run build +# Build for production +bun run build # or npm run build -# 预览生产构建 -bun run preview # 或 npm run preview +# Preview production build +bun run preview # or npm run preview ``` -访问 http://localhost:5173 开始使用。 +Access the dashboard at http://localhost:8082 -### 配置连接 +### Standalone Server -编辑 `src/lib/api.ts` 中的 API_BASE 常量指向您的 Cortex Memory Service： +The project includes a standalone Bun server that can be compiled to a native executable: -```typescript -const API_BASE = 'http://localhost:8080/api/v2'; -``` +```bash +# Run the server +bun run serve -## 📖 使用指南 +# Compile to standalone executable +bun run compile -### 仪表板概览 +# Cross-compile for all platforms +bun run compile:all +``` -主仪表板提供： -- **系统状态**: 实时显示服务状态和数据目录使用情况 -- **活动图表**: 展示最近 24 小时的消息活动和搜索频率 -- **快速操作**: 常用功能的快捷访问按钮 +## 📖 Usage Guide -### 浏览记忆 +### Dashboard Overview -1. 点击左侧导航栏的 "Memories" -2. 选择维度（用户、代理、会话、资源） -3. 浏览记忆结构，点击展开查看内容 -4. 使用顶部按钮切换抽象/概览/完整内容视图 +The main dashboard provides: +- **Tenants Table**: Display all tenants with statistics +- **Service Status Card**: Health status, version, LLM availability +- **Storage Card**: Total size and file counts -### 高级搜索 +### Browsing Memories -1. 导航到 "Search" 页面 -2. 输入搜索查询 -3. 应用过滤器： - - 范围：会话、用户、代理、全局 - - 时间范围：自定义日期区间 - - 最低相关性分数 -4. 查看结果并点击查看详细内容 +1. Click "Memories" in the navigation +2. Select a dimension tab (User, Session, Agent, Resources) +3. Browse the file tree structure +4. Click on files to view content +5. Edit content directly in the editor +6. Save changes with the Save button -### 监控系统 +### Searching -1. 仪表板自动显示系统健康状态 -2. 绿色指示器表示正常，黄色警告，红色错误 -3. 点击指示器查看详细错误信息和解决方案 +1. Navigate to "Search" page +2. Enter search query +3. Select scope (All, User, Session, Agent) +4. Set result limit +5. View results with relevance scores +6. Expand to see full content -## 🛠️ 技术架构 +## 🛠️ Architecture -### 前端技术栈 -- **Svelte 5**: 响应式 UI 框架，使用最新的 runes API -- **Vite**: 快速构建工具和开发服务器 -- **TypeScript**: 类型安全的 JavaScript 超集 -- **Svelte Routing**: 客户端路由解决方案 +### Project Structure -### 项目结构 ``` src/ ├── lib/ -│ ├── api.ts # API 客户端 -│ ├── types.ts # TypeScript 类型定义 -│ ├── components/ # 可复用组件 -│ ├── pages/ # 页面组件 -│ └── stores/ # 状态管理 -├── routes/ # 路由定义 -├── app.html # HTML 模板 -└── main.ts # 应用入口点 +│ ├── api.ts # API client for cortex-mem-service +│ ├── types.ts # TypeScript interfaces +│ ├── components/ +│ │ └── TenantSelector.svelte # Tenant selection dropdown +│ ├── pages/ +│ │ ├── Dashboard.svelte # Main dashboard +│ │ ├── Memories.svelte # Memory browser +│ │ └── Search.svelte # Search interface +│ └── stores/ +│ └── tenant.ts # Global tenant state +├── app.css # Global styles +├── App.svelte # Main router +└── main.ts # App bootstrap ``` -### API 集成 +### Frontend Tech Stack + +- **Svelte 5**: Reactive UI framework with runes API (`$state`, `$derived`, `$effect`) +- **Vite**: Fast build tool and development server +- **TypeScript**: Type-safe JavaScript +- **Bun**: Runtime and package manager -仪表板通过 REST API 与 Cortex Memory Service 通信： -- 获取会话列表和详情 -- 搜索和浏览记忆内容 -- 检索系统状态和健康信息 -- 执行记忆提取和索引操作 +### Server (server.ts) -## 🔧 配置选项 +A standalone Bun server with: -### 环境变量 +**Command-line Options:** +``` +-p, --port <number> Port to run server on (default: 8159) +--api-target <url> API target URL (default: http://localhost:8085) +--no-browser Don't open browser automatically +--headless Same as --no-browser +-h, --help Show help message +``` -创建 `.env` 文件配置环境变量： +**Environment Variables:** +- `PORT`: Server port +- `API_TARGET`: Backend API URL for proxying -```bash -# API 服务器地址 -VITE_API_BASE_URL=http://localhost:8080/api/v2 +## 📡 API Reference + +### API Client Methods + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `getHealth()` | `GET /health` | Health check | +| `listTenants()` | `GET /api/v2/tenants/tenants` | List all tenants | +| `switchTenant(tenantId)` | `POST /api/v2/tenants/tenants/switch` | Switch active tenant | +| `listDirectory(path)` | `GET /api/v2/filesystem/list?uri=` | List directory contents | +| `readFile(path)` | `GET /api/v2/filesystem/read/` | Read file content | +| `writeFile(path, content)` | `POST /api/v2/filesystem/write` | Write file content | +| `getDirectoryStats(uri)` | `GET /api/v2/filesystem/stats?uri=` | Get directory statistics | +| `getSessions()` | `GET /api/v2/sessions` | Get session list | +| `search(keyword, scope, limit)` | `POST /api/v2/search` | Vector search | -# 应用标题 -VITE_APP_TITLE=Cortex Memory Insights +### Type Definitions -# 主题设置 -VITE_DEFAULT_THEME=dark +```typescript +interface HealthStatus { + status: string; + service: string; + version: string; + llm_available: boolean; +} + +interface FileEntryResponse { + uri: string; + name: string; + is_directory: boolean; + size: number; + modified: string; +} + +interface SearchResult { + uri: string; + score: number; + snippet: string; + content?: string; + source: string; +} -# 自动刷新间隔（毫秒） -VITE_REFRESH_INTERVAL=5000 +interface TenantInfo { + user_memories: number; + sessions: number; + agents: number; + resources: number; + files: number; + storage_bytes: number; +} ``` -### 自定义样式 +## 🔧 Configuration + +### Vite Configuration (vite.config.ts) -编辑 `src/app.css` 修改样式变量： +```typescript +export default defineConfig({ + server: { + port: 8082, + proxy: { + '/api/v2': 'http://localhost:8085', + '/health': 'http://localhost:8085', + }, + }, +}); +``` + +### Environment Variables + +Create `.env` file: + +```bash +# API server address (optional, uses proxy by default) +VITE_API_BASE_URL=http://localhost:8085/api/v2 +``` + +### Custom Styles + +Edit `src/app.css` to modify theme variables: ```css :root { @@ -156,122 +232,76 @@ VITE_REFRESH_INTERVAL=5000 } ``` -## 🧪 开发指南 - -### 添加新页面 - -1. 在 `src/lib/pages/` 创建新页面组件 -2. 在 `src/App.svelte` 添加路由和导航 -3. 更新类型定义（如需要） - -### 自定义组件 +## 🧪 Development -可复用组件存放在 `src/lib/components/`： -- `MemoryCard.svelte` - 记忆卡片显示 -- `SearchBox.svelte` - 搜索输入框 -- `StatusIndicator.svelte` - 状态指示器 -- `Chart.svelte` - 通用图表组件 +### Adding New Pages -### 状态管理 +1. Create component in `src/lib/pages/` +2. Add route in `src/App.svelte` +3. Add navigation link -使用 Svelte 5 的 runes 进行状态管理： -- `$state` - 响应式状态 -- `$derived` - 派生状态 -- `$effect` - 副作用处理 +### State Management -## 📊 性能优化 +Use Svelte 5 runes: -### 代码分割 -- 路由级别代码自动分割 -- 按需加载大型组件 -- 延迟加载图表库 - -### 缓存策略 -- API 响应缓存（5分钟） -- 静态资源长期缓存 -- 浏览器缓存优化 - -### 优化技巧 ```typescript -// 使用 $derived 避免不必要的计算 +// Reactive state +let memories = $state<FileEntry[]>([]); + +// Derived state const filteredMemories = $derived( - memories.filter(m => m.score > minScore) + memories.filter(m => m.name.includes(searchQuery)) ); -// 延迟加载大型数据 -async function loadDetailedView(uri: string) { - const content = await api.getMemory(uri); - detailedContent.set(content); -} +// Side effects +$effect(() => { + console.log('Memories updated:', memories.length); +}); ``` -## 🚨 常见问题 - -### 连接失败 - -**问题**: 无法连接到 Cortex Memory Service -**解决**: -1. 检查服务是否运行（`http://localhost:8080/health`） -2. 验证 CORS 设置 -3. 检查防火墙配置 - -### 数据显示错误 - -**问题**: 记忆内容显示异常 -**解决**: -1. 刷新页面重新加载数据 -2. 检查服务端日志 -3. 验证数据格式兼容性 - -### 性能问题 +## 🚨 Troubleshooting -**问题**: 仪表板响应缓慢 -**解决**: -1. 减少同时显示的数据量 -2. 增加搜索过滤条件 -3. 检查网络延迟 +### Connection Failed -## 🛣️ 路线图 +**Problem**: Cannot connect to Cortex Memory Service -### 短期计划 -- [ ] 实时 WebSocket 连接 -- [ ] 记忆关系图谱可视化 -- [ ] 批量操作功能 -- [ ] 导出/导入工具 +**Solution**: +1. Check if service is running (`http://localhost:8085/health`) +2. Verify CORS settings +3. Check firewall configuration -### 长期计划 -- [ ] 多租户支持 -- [ ] 自定义仪表板 -- [ ] 插件系统 -- [ ] 移动应用版本 +### Data Display Issues -## 🤝 贡献指南 +**Problem**: Memory content displays incorrectly -欢迎贡献！请遵循以下步骤： +**Solution**: +1. Refresh page to reload data +2. Check server logs +3. Verify data format compatibility -1. Fork 项目 -2. 创建功能分支 -3. 提交更改 -4. 创建 Pull Request +## 📦 Scripts -代码风格： -- 使用 2 空格缩进 -- 组件命名使用 PascalCase -- 文件名使用 kebab-case -- 提交消息使用 Conventional Commits +| Script | Purpose | +|--------|---------| +| `dev` | Start Vite dev server | +| `build` | Build production bundle | +| `preview` | Preview production build | +| `serve` | Run Bun standalone server | +| `compile` | Compile to standalone executable | +| `compile:all` | Cross-compile for all platforms | -## 📄 许可证 +## 📄 License -MIT 许可证 - 详见 [LICENSE](../../LICENSE) 文件 +MIT License - see the [LICENSE](../../LICENSE) file for details. -## 🔗 相关资源 +## 🔗 Related Resources -- [Cortex Memory 主文档](../README.md) +- [Cortex Memory Main Documentation](../README.md) - [Cortex Memory Service](../cortex-mem-service/README.md) -- [Cortex Memory 核心](../cortex-mem-core/README.md) -- [Svelte 文档](https://svelte.dev/docs) -- [Vite 文档](https://vitejs.dev/) +- [Cortex Memory Core](../cortex-mem-core/README.md) +- [Svelte Documentation](https://svelte.dev/docs) +- [Vite Documentation](https://vitejs.dev/) --- -**Built with ❤️ using Svelte and TypeScript** \ No newline at end of file +**Built with ❤️ using Svelte 5 and TypeScript** diff --git a/cortex-mem-mcp/README.md b/cortex-mem-mcp/README.md index 9a7fb83..46b22f7 100644 --- a/cortex-mem-mcp/README.md +++ b/cortex-mem-mcp/README.md @@ -1,43 +1,43 @@ # Cortex Memory MCP Server -`cortex-mem-mcp` 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的服务器，使 AI 助手能够与 Cortex Memory 系统进行交互，实现持久化记忆存储和检索。 +`cortex-mem-mcp` is a server implementation based on [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) that enables AI assistants to interact with the Cortex Memory system for persistent memory storage and retrieval. -## 🧠 功能概述 +## 🧠 Overview -Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： +Cortex Memory MCP Server provides six core tools for AI assistants: -- 📝 **存储记忆**: 将对话中的关键信息保存到长期记忆 -- 🔍 **搜索记忆**: 使用语义向量搜索检索相关记忆 -- 📋 **列出记忆**: 浏览已存储的记忆条目 -- 📄 **获取记忆**: 读取特定记忆的完整内容 -- 🗑️ **删除记忆**: 删除指定的记忆条目 -- 📊 **获取摘要**: 获取记忆的 L0 抽象摘要 +- 📝 **store_memory**: Store new memories from conversations +- 🔍 **query_memory**: Semantic vector search with L0/L1/L2 layered results +- 📋 **list_memories**: Browse stored memory entries +- 📄 **get_memory**: Retrieve complete memory content +- 🗑️ **delete_memory**: Delete specific memory entries +- 📊 **get_abstract**: Get L0 abstract summary (~100 tokens) -## 🛠️ MCP 工具 +## 🛠️ MCP Tools ### 1. `store_memory` -存储新的记忆到 Cortex Memory 系统中。 +Store a new memory in the Cortex Memory system. -#### 参数 +#### Parameters -| 参数 | 类型 | 必需 | 默认值 | 描述 | -|------|------|------|--------|------| -| `content` | string | ✅ | - | 要存储的记忆内容 | -| `thread_id` | string | ❌ | "default" | 会话ID，用于组织相关记忆 | -| `role` | string | ❌ | "user" | 消息角色: "user", "assistant", "system" | +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `content` | string | ✅ | - | Memory content to store | +| `thread_id` | string | ❌ | `"default"` | Session ID for organizing related memories | +| `role` | string | ❌ | `"user"` | Message role: `"user"`, `"assistant"`, or `"system"` | -#### 示例 +#### Example Request ```json { - "content": "用户偏好使用深色主题，并且喜欢使用 Vim 键位绑定", + "content": "User prefers dark theme and likes vim keybindings", "thread_id": "user-preferences", "role": "user" } ``` -#### 响应 +#### Response ```json { @@ -47,73 +47,82 @@ Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： } ``` +--- + ### 2. `query_memory` -使用语义向量搜索检索相关记忆，支持 L0/L1/L2 分层返回。 +Search memories using semantic vector search with L0/L1/L2 layered results. -#### 参数 +#### Parameters -| 参数 | 类型 | 必需 | 默认值 | 描述 | -|------|------|------|--------|------| -| `query` | string | ✅ | - | 搜索查询字符串 | -| `thread_id` | string | ❌ | - | 限制搜索到此会话 | -| `limit` | number | ❌ | 10 | 最大结果数量 | -| `scope` | string | ❌ | "session" | 搜索范围: "session", "user", "agent" | +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `query` | string | ✅ | - | Search query string | +| `thread_id` | string | ❌ | - | Limit search to this session | +| `limit` | number | ❌ | `10` | Maximum number of results | +| `scope` | string | ❌ | `"session"` | Search scope: `"session"`, `"user"`, or `"agent"` | -#### 搜索范围说明 +#### Scope URI Mapping -- **`session`**: 搜索会话记忆 (`cortex://session`) -- **`user`**: 搜索用户相关的长期记忆 (`cortex://user`) -- **`agent`**: 搜索 Agent 记忆 (`cortex://agent`) +| Scope | URI Pattern | +|-------|-------------| +| `session` | `cortex://session` | +| `user` | `cortex://user` | +| `agent` | `cortex://agent` | +| (with thread_id) | `cortex://session/{thread_id}` | -#### 示例 +#### Example Request ```json { - "query": "Rust OAuth 实现方法", + "query": "Rust OAuth implementation method", "thread_id": "technical-discussions", "limit": 5, "scope": "session" } ``` -#### 响应 +#### Response ```json { "success": true, - "query": "Rust OAuth 实现方法", + "query": "Rust OAuth implementation method", "results": [ { "uri": "cortex://session/tech-disc/timeline/2024/01/10/09_15_30_def456.md", "score": 0.92, - "snippet": "...讨论了使用 OAuth2 客户端库实现 Rust 应用中的身份验证..." + "snippet": "...discussed using OAuth2 client library for authentication in Rust applications..." } ], "total": 1 } ``` +--- + ### 3. `list_memories` -列出指定 URI 路径下的记忆内容。 +List memories from a specific URI path. -#### 参数 +#### Parameters -| 参数 | 类型 | 必需 | 默认值 | 描述 | -|------|------|------|--------|------| -| `uri` | string | ❌ | "cortex://session" | 要列出的 URI 路径 | -| `limit` | number | ❌ | 50 | 最大条目数 | -| `include_abstracts` | boolean | ❌ | false | 是否包含 L0 摘要 | +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `uri` | string | ❌ | `"cortex://session"` | URI path to list | +| `limit` | number | ❌ | `50` | Maximum number of entries | +| `include_abstracts` | boolean | ❌ | `false` | Include L0 abstracts | -#### 支持的 URI 模式 +#### Supported URI Patterns -- `"cortex://session"` - 列出所有会话 -- `"cortex://user/{user-id}"` - 列出指定用户的记忆 -- `"cortex://agent/{agent-id}"` - 列出指定 agent 的记忆 -- `"cortex://session/{session-id}/timeline"` - 列出会话的时间线 +| URI Pattern | Description | +|-------------|-------------| +| `cortex://session` | List all sessions | +| `cortex://user/{user-id}` | List user memories | +| `cortex://agent/{agent-id}` | List agent memories | +| `cortex://session/{session-id}/timeline` | List session timeline | -#### 示例 +#### Example Request ```json { @@ -123,7 +132,7 @@ Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： } ``` -#### 响应 +#### Response ```json { @@ -135,24 +144,26 @@ Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： "uri": "cortex://session/user-preferences", "is_directory": true, "size": 2048, - "abstract_text": "用户偏好设置和选项" + "abstract_text": "User preference settings and options" } ], "total": 1 } ``` +--- + ### 4. `get_memory` -获取特定记忆的完整内容。 +Retrieve complete content of a specific memory. -#### 参数 +#### Parameters -| 参数 | 类型 | 必需 | 默认值 | 描述 | -|------|------|------|--------|------| -| `uri` | string | ✅ | - | 记忆的完整 URI | +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `uri` | string | ✅ | - | Full URI of the memory | -#### 示例 +#### Example Request ```json { @@ -160,27 +171,29 @@ Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： } ``` -#### 响应 +#### Response ```json { "success": true, "uri": "cortex://session/user-preferences/timeline/2024/01/15/14_30_45_abc123.md", - "content": "# Message\n\n用户偏好使用深色主题，并且喜欢使用 Vim 键位绑定。\n\n---\n*Timestamp: 2024-01-15T14:30:45Z*\n*Role: user*" + "content": "# Message\n\nUser prefers dark theme and likes vim keybindings.\n\n---\n*Timestamp: 2024-01-15T14:30:45Z*\n*Role: user*" } ``` +--- + ### 5. `delete_memory` -删除指定的记忆条目。 +Delete a specific memory entry. -#### 参数 +#### Parameters -| 参数 | 类型 | 必需 | 默认值 | 描述 | -|------|------|------|--------|------| -| `uri` | string | ✅ | - | 要删除的记忆 URI | +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `uri` | string | ✅ | - | URI of the memory to delete | -#### 示例 +#### Example Request ```json { @@ -188,7 +201,7 @@ Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： } ``` -#### 响应 +#### Response ```json { @@ -197,17 +210,19 @@ Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： } ``` +--- + ### 6. `get_abstract` -获取指定记忆的 L0 抽象摘要（约 100 tokens），用于快速判断相关性。 +Get the L0 abstract summary (~100 tokens) of a memory for quick relevance checking. -#### 参数 +#### Parameters -| 参数 | 类型 | 必需 | 默认值 | 描述 | -|------|------|------|--------|------| -| `uri` | string | ✅ | - | 记忆的 URI | +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `uri` | string | ✅ | - | URI of the memory | -#### 示例 +#### Example Request ```json { @@ -215,47 +230,47 @@ Cortex Memory MCP 服务器提供六个核心工具，让 AI 助手能够： } ``` -#### 响应 +#### Response ```json { "success": true, "uri": "cortex://session/user-preferences/timeline/2024/01/15/14_30_45_abc123.md", - "abstract_text": "用户偏好设置：深色主题，Vim 键位绑定" + "abstract_text": "User preferences: dark theme, vim keybindings" } ``` -## 🚀 安装与配置 +## 🚀 Installation & Configuration -### 构建要求 +### Build Requirements -- Rust 1.70 或更高版本 -- 跨平台支持：Linux、macOS、Windows +- Rust 1.70 or later +- Cross-platform support: Linux, macOS, Windows -### 构建 +### Build ```bash -# 克隆仓库 +# Clone repository git clone https://github.com/sopaco/cortex-mem.git cd cortex-mem -# 构建服务器 +# Build the server cargo build --release --bin cortex-mem-mcp -# 二进制位置 +# Binary location ./target/release/cortex-mem-mcp ``` -### 命令行参数 +### Command-line Arguments -| 参数 | 默认值 | 描述 | -|------|--------|------| -| `--config` | `config.toml` | 配置文件路径 | -| `--tenant` | `default` | 租户 ID | +| Argument | Default | Description | +|----------|---------|-------------| +| `--config` / `-c` | `config.toml` | Path to configuration file | +| `--tenant` | `default` | Tenant ID for memory isolation | -### 配置 Claude Desktop +### Configure Claude Desktop -编辑 Claude Desktop 配置文件： +Edit Claude Desktop configuration file: **macOS**: ```bash @@ -267,7 +282,7 @@ open ~/Library/Application\ Support/Claude/claude_desktop_config.json notepad %APPDATA%\Claude\claude_desktop_config.json ``` -添加以下配置： +Add configuration: ```json { @@ -286,15 +301,15 @@ notepad %APPDATA%\Claude\claude_desktop_config.json } ``` -### 配置文件 (config.toml) +### Configuration File (config.toml) ```toml [cortex] -# 数据目录（可选，默认为当前目录下的 cortex-data） +# Data directory (optional, has smart defaults) data_dir = "/path/to/cortex-data" [llm] -# LLM API 配置 +# LLM API configuration api_base_url = "https://api.openai.com/v1" api_key = "your-api-key" model_efficient = "gpt-4o-mini" @@ -302,7 +317,7 @@ temperature = 0.1 max_tokens = 4096 [embedding] -# 嵌入配置 +# Embedding configuration api_base_url = "https://api.openai.com/v1" api_key = "your-embedding-api-key" model_name = "text-embedding-3-small" @@ -310,183 +325,180 @@ batch_size = 10 timeout_secs = 30 [qdrant] -# 向量数据库配置 +# Vector database configuration url = "http://localhost:6333" collection_name = "cortex_memories" embedding_dim = 1536 timeout_secs = 30 ``` -## 🔄 MCP 工作流 +### Data Directory Resolution + +Priority order: +1. `cortex.data_dir` config value +2. `CORTEX_DATA_DIR` environment variable +3. System app data directory (e.g., `%APPDATA%/tars/cortex` on Windows) +4. Fallback: `./.cortex` in current directory + +## 🔄 MCP Workflow -### 典型记忆工作流 +### Typical Memory Workflow -1. **对话开始**: Claude 检索相关记忆 ```javascript -// Claude 查询用户偏好 +// 1. Start of conversation: Query relevant memories await query_memory({ - query: "用户偏好", + query: "user preferences", scope: "user", limit: 5 }); -``` -2. **存储新信息**: 将对话中关键信息存储 -```javascript -// Claude 存储新的发现 +// 2. During conversation: Store new information await store_memory({ - content: "用户提到他们正在学习 Rust 异步编程", + content: "User mentioned they are learning Rust async programming", thread_id: "learning-journey", role: "user" }); -``` -3. **对话结束**: 生成摘要并存储 -```javascript -// Claude 总结讨论要点 +// 3. End of conversation: Store summary await store_memory({ - content: "讨论了 Rust 的 async/await、Pin 和 Future，用户理解了基本概念", + content: "Discussed Rust async/await, Pin, and Future. User understood the basics.", thread_id: "rust-async-discussion", role: "assistant" }); ``` -### 高级搜索策略 - -结合多种工具获取最佳结果： +### Advanced Search Strategy ```javascript -// 1. 先从会话中搜索 +// 1. Search in sessions first const sessionResults = await query_memory({ - query: "Rust 错误处理", + query: "Rust error handling", scope: "session", limit: 5 }); -// 2. 如果需要更多上下文，搜索用户记忆 +// 2. If more context needed, search user memories if (sessionResults.results.length < 3) { const userResults = await query_memory({ - query: "Rust 错误处理", + query: "Rust error handling", scope: "user", limit: 5 }); - // 合并结果 + // Merge results sessionResults.results.push(...userResults.results); } -// 3. 获取完整内容 +// 3. Get full content const fullContent = await get_memory({ uri: sessionResults.results[0].uri }); -// 4. 或者只获取摘要快速查看 +// 4. Or get abstract for quick preview const abstract = await get_abstract({ uri: sessionResults.results[0].uri }); ``` -## 🔧 故障排除 +## 🔧 Troubleshooting -### 常见问题 +### Common Issues -#### 1. 连接失败 +#### 1. Connection Failed -**错误**: `Failed to connect to MCP server` +**Error**: `Failed to connect to MCP server` -**解决方案**: -1. 检查 Claude Desktop 配置文件路径 -2. 验证二进制文件路径和权限 -3. 查看日志输出 +**Solution**: +1. Check Claude Desktop configuration file path +2. Verify binary file path and permissions +3. View log output ```bash -# 测试运行 +# Test run RUST_LOG=debug ./cortex-mem-mcp --config config.toml --tenant default ``` -#### 2. 记忆存储失败 +#### 2. Memory Storage Failed -**错误**: `Failed to store memory` +**Error**: `Failed to store memory` -**解决方案**: -1. 检查数据目录权限 -2. 验证 LLM API 配置 -3. 确认 Qdrant 服务运行正常 -4. 检查 embedding 配置 +**Solution**: +1. Check data directory permissions +2. Verify LLM API configuration +3. Confirm Qdrant service is running +4. Check embedding configuration ```bash -# 检查目录权限 +# Check directory permissions ls -la ./cortex-data chmod 755 ./cortex-data -# 检查 Qdrant 连接 +# Check Qdrant connection curl http://localhost:6333/collections ``` -#### 3. 搜索无结果 +#### 3. Empty Search Results -**错误**: `Search returned empty results` +**Error**: `Search returned empty results` -**解决方案**: -1. 检查是否有记忆存储 -2. 验证搜索查询格式 -3. 确认搜索范围 +**Solution**: +1. Check if memories exist +2. Verify search query format +3. Confirm search scope ```javascript -// 测试搜索 +// Test listing await list_memories({ uri: "cortex://session", limit: 50 }); ``` -#### 4. Qdrant 连接失败 +#### 4. Qdrant Connection Failed -**错误**: `Failed to connect to Qdrant` +**Error**: `Failed to connect to Qdrant` -**解决方案**: -1. 确保 Qdrant 服务正在运行 -2. 检查 URL 配置是否正确 -3. 验证集合名称是否存在 +**Solution**: +1. Ensure Qdrant service is running +2. Check URL configuration +3. Verify collection name exists ```bash -# 启动 Qdrant (Docker) +# Start Qdrant (Docker) docker run -p 6333:6333 qdrant/qdrant -# 检查连接 +# Check connection curl http://localhost:6333 ``` -### 调试模式 - -启用详细日志进行问题诊断： +### Debug Mode ```bash -# 启用调试模式 +# Enable verbose logging RUST_LOG=debug ./cortex-mem-mcp --config config.toml --tenant default ``` -## 🔗 相关资源 +## 🔗 Related Resources -- [Cortex Memory 主文档](../README.md) -- [Cortex Memory 核心](../cortex-mem-core/README.md) -- [Cortex Memory 工具](../cortex-mem-tools/README.md) +- [Cortex Memory Main Documentation](../README.md) +- [Cortex Memory Core](../cortex-mem-core/README.md) +- [Cortex Memory Tools](../cortex-mem-tools/README.md) - [Model Context Protocol](https://modelcontextprotocol.io/) -- [Claude Desktop MCP 文档](https://docs.anthropic.com/claude/docs/mcp) +- [Claude Desktop MCP Documentation](https://docs.anthropic.com/claude/docs/mcp) -## 🤝 贡献 +## 🤝 Contributing -欢迎贡献！请遵循以下步骤： +Contributions are welcome! Please follow these steps: -1. Fork 项目 -2. 创建功能分支 (`git checkout -b feature/amazing-feature`) -3. 提交更改 (`git commit -m 'Add amazing feature'`) -4. 推送到分支 (`git push origin feature/amazing-feature`) -5. 创建 Pull Request +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Create a Pull Request -## 📄 许可证 +## 📄 License -MIT 许可证 - 详见 [LICENSE](../../LICENSE) 文件 +MIT License - see the [LICENSE](../../LICENSE) file for details. --- -**Built with ❤️ using Rust and Model Context Protocol** +**Built with ❤️ using Rust and Model Context Protocol** \ No newline at end of file diff --git a/cortex-mem-mcp/test-mcp.sh b/cortex-mem-mcp/test-mcp.sh deleted file mode 100755 index dcad794..0000000 --- a/cortex-mem-mcp/test-mcp.sh +++ /dev/null @@ -1,53 +0,0 @@ -#!/bin/bash -# MCP Server Manual Test Script - -echo "================================" -echo "Cortex-Mem MCP Server Manual Test" -echo "================================" -echo "" - -MCP_BIN="./target/release/cortex-mem-mcp" - -if [ ! -f "$MCP_BIN" ]; then - echo "❌ MCP binary not found. Building..." - cargo build --release --bin cortex-mem-mcp -fi - -echo "📝 Testing MCP Server..." -echo "" - -# Test 1: Initialize -echo "Test 1: Initialize" -echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | $MCP_BIN 2>/dev/null & -PID=$! -sleep 1 -kill $PID 2>/dev/null -echo "✓ Initialize test completed" -echo "" - -# Test 2: Tools List -echo "Test 2: List Tools" -(echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' && sleep 0.5) | $MCP_BIN 2>/dev/null | jq -r '.result.tools[].name' 2>/dev/null -echo "" - -# Test 3: Store Memory -echo "Test 3: Store Memory" -REQUEST='{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"store_memory","arguments":{"content":"测试记忆内容","thread_id":"test-mcp"}}}' -(echo "$REQUEST" && sleep 0.5) | $MCP_BIN 2>/dev/null | jq -r '.result.content[0].text' 2>/dev/null -echo "" - -# Test 4: List Memories -echo "Test 4: List Memories" -REQUEST='{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_memories","arguments":{"thread_id":"test-mcp"}}}' -(echo "$REQUEST" && sleep 0.5) | $MCP_BIN 2>/dev/null | jq -r '.result.content[0].text' 2>/dev/null -echo "" - -echo "================================" -echo "✅ Manual tests completed!" -echo "================================" -echo "" -echo "💡 For full integration testing:" -echo " 1. Configure Claude Desktop (see cortex-mem-mcp/README.md)" -echo " 2. Restart Claude Desktop" -echo " 3. Ask Claude to use cortex-mem tools" -echo "" diff --git a/cortex-mem-rig/README.md b/cortex-mem-rig/README.md index 26a6672..92835d3 100644 --- a/cortex-mem-rig/README.md +++ b/cortex-mem-rig/README.md @@ -1,321 +1,416 @@ # Cortex Memory Rig Integration -`cortex-mem-rig` 提供与 [Rig](https://github.com/coreylowman/rig) AI 框架的集成，使 AI 代理能够通过工具调用与 Cortex Memory 系统进行交互。 +`cortex-mem-rig` provides integration with the [Rig](https://github.com/0xPlaygrounds/rig) AI framework, enabling AI agents to interact with the Cortex Memory system through tool calls. -## 🧠 概述 +## 🧠 Overview -Cortex Memory Rig 实现了三层架构访问工具，允许 AI 代理高效地检索和操作记忆： +Cortex Memory Rig implements OpenViking-style tiered access tools, allowing AI agents to efficiently retrieve and manipulate memories: -### 三层访问架构 +### Three-Tier Access Architecture -| 层级 | 大小 | 用途 | 工具 | -|------|------|------|------| -| **L0 Abstract** | ~100 tokens | 快速相关性判断 | `abstract_tool` | -| **L1 Overview** | ~500-2000 tokens | 部分上下文理解 | `overview_tool` | -| **L3 Full** | 完整内容 | 深度分析和处理 | `read_tool` | +| Layer | Size | Purpose | Tool | +|-------|------|---------|------| +| **L0 Abstract** | ~100 tokens | Quick relevance judgment | `abstract_tool` | +| **L1 Overview** | ~2000 tokens | Partial context understanding | `overview_tool` | +| **L2 Full** | Complete content | Deep analysis and processing | `read_tool` | -### 核心工具集 +### Tool Categories -- 📊 **分层访问工具**: `abstract()`, `overview()`, `read()` -- 🔍 **搜索工具**: `search()`, `find()` -- 📁 **文件系统工具**: `ls()`, `explore()`, `store()` +- 📊 **Tiered Access Tools**: `abstract`, `overview`, `read` +- 🔍 **Search Tools**: `search`, `find` +- 📁 **Filesystem Tools**: `ls`, `explore` +- 💾 **Storage Tools**: `store` -## 🚀 快速开始 +## 🚀 Quick Start -### 安装 +### Installation ```toml [dependencies] cortex-mem-rig = { path = "../cortex-mem-rig" } cortex-mem-tools = { path = "../cortex-mem-tools" } -rig-core = "0.31" +cortex-mem-core = { path = "../cortex-mem-core" } +rig-core = "0.11" +tokio = { version = "1", features = ["full"] } ``` -### 基本使用 +### Basic Usage ```rust -use cortex_mem_rig::MemoryTools; -use cortex_mem_tools::MemoryOperations; -use rig::agents::Agent; +use cortex_mem_rig::{MemoryTools, create_memory_tools_with_tenant_and_vector}; +use cortex_mem_core::llm::{LLMClientImpl, LLMConfig}; use std::sync::Arc; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { - // 创建记忆操作 - let operations = Arc::new(MemoryOperations::from_data_dir("./cortex-data").await?); + // Create LLM client + let llm_config = LLMConfig { + api_base_url: "https://api.openai.com/v1".to_string(), + api_key: "your-api-key".to_string(), + model_efficient: "gpt-4o-mini".to_string(), + temperature: 0.1, + max_tokens: 4096, + }; + let llm_client = Arc::new(LLMClientImpl::new(llm_config)?); - // 创建 Rig 工具集 - let memory_tools = MemoryTools::new(operations); + // Create memory tools with vector search support + let memory_tools = create_memory_tools_with_tenant_and_vector( + "./cortex-data", + "default", + llm_client, + "http://localhost:6333", + "cortex_memories", + "https://api.openai.com/v1", + "your-embedding-key", + "text-embedding-3-small", + Some(1536), + None, + ).await?; - // 创建 agent 并附加工具 - let agent = Agent::new("gpt-4o-mini") - .preamble("你是一个具有持久记忆的 AI 助手。") - .tool(memory_tools.abstract_tool()) - .tool(memory_tools.overview_tool()) - .tool(memory_tools.search_tool()) - .build(); + // Get individual tools for Rig agent + let abstract_tool = memory_tools.abstract_tool(); + let overview_tool = memory_tools.overview_tool(); + let read_tool = memory_tools.read_tool(); + let search_tool = memory_tools.search_tool(); + let store_tool = memory_tools.store_tool(); - // 使用 agent... + // Use with Rig agent... Ok(()) } ``` -## 📚 API 参考 +## 📚 API Reference ### MemoryTools -主要的工具集合类，提供对不同层级工具的访问。 +Main struct providing access to all memory tools. ```rust +pub struct MemoryTools { + operations: Arc<MemoryOperations>, +} + impl MemoryTools { + /// Create from existing MemoryOperations pub fn new(operations: Arc<MemoryOperations>) -> Self - - // 三层访问工具 + + /// Get underlying operations + pub fn operations(&self) -> &Arc<MemoryOperations> + + // Tiered Access Tools pub fn abstract_tool(&self) -> AbstractTool pub fn overview_tool(&self) -> OverviewTool pub fn read_tool(&self) -> ReadTool - // 搜索工具 + // Search Tools pub fn search_tool(&self) -> SearchTool pub fn find_tool(&self) -> FindTool - // 文件系统工具 + // Filesystem Tools pub fn ls_tool(&self) -> LsTool pub fn explore_tool(&self) -> ExploreTool - pub fn store_tool(&self) -> StoreTool - // 获取底层操作 - pub fn operations(&self) -> &Arc<MemoryOperations> + // Storage Tools + pub fn store_tool(&self) -> StoreTool } ``` -### 分层访问工具 +### Factory Functions + +```rust +/// Create MemoryTools from existing MemoryOperations +pub fn create_memory_tools(operations: Arc<MemoryOperations>) -> MemoryTools + +/// Create MemoryTools with tenant isolation and vector search support +pub async fn create_memory_tools_with_tenant_and_vector( + data_dir: &str, + tenant_id: &str, + llm_client: Arc<dyn LLMClient>, + qdrant_url: &str, + qdrant_collection: &str, + embedding_api_base_url: &str, + embedding_api_key: &str, + embedding_model_name: &str, + embedding_dim: Option<usize>, + user_id: Option<String>, +) -> Result<MemoryTools, Box<dyn std::error::Error>> +``` + +## 🛠️ Tool Definitions + +### Tiered Access Tools -#### AbstractTool +#### AbstractTool (`"abstract"`) -获取内容的 L0 抽象摘要（约 100 tokens），用于快速判断相关性。 +Get L0 abstract (~100 tokens) for quick relevance checking. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct AbstractArgs { - pub uri: String, + pub uri: String, // Required: Memory URI } +``` -#[derive(Debug, Serialize, Deserialize)] +**Response:** +```rust pub struct AbstractResponse { pub uri: String, pub abstract_text: String, - pub layer: String, + pub layer: String, // "L0" pub token_count: usize, } - -impl Tool for AbstractTool { - const NAME: &'static str = "abstract"; - // ... -} ``` -**示例使用**: -```rust -let result = agent.prompt( - "获取cortex://user/user-123/preferences.md的摘要" -).await?; -``` +#### OverviewTool (`"overview"`) -#### OverviewTool - -获取内容的 L1 概览（约 500-2000 tokens），用于部分上下文理解。 +Get L1 overview (~2000 tokens) for partial context. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct OverviewArgs { - pub uri: String, + pub uri: String, // Required: Memory URI } +``` -#[derive(Debug, Serialize, Deserialize)] +**Response:** +```rust pub struct OverviewResponse { pub uri: String, pub overview_text: String, - pub layer: String, + pub layer: String, // "L1" pub token_count: usize, - pub sections: Vec<String>, -} - -impl Tool for OverviewTool { - const NAME: &'static str = "overview"; - // ... } ``` -#### ReadTool +#### ReadTool (`"read"`) -获取完整内容（L3），用于深度分析。 +Get L2 full content for deep analysis. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct ReadArgs { - pub uri: String, + pub uri: String, // Required: Memory URI } +``` -#[derive(Debug, Serialize, Deserialize)] +**Response:** +```rust pub struct ReadResponse { pub uri: String, pub content: String, - pub layer: String, + pub layer: String, // "L2" pub token_count: usize, - pub sections: Vec<String>, -} - -impl Tool for ReadTool { - const NAME: &'static str = "read"; - // ... + pub metadata: Option<FileMetadata>, } ``` -### 搜索工具 +### Search Tools -#### SearchTool +#### SearchTool (`"search"`) -执行智能搜索，支持多种模式。 +Intelligent vector search with LLM query rewriting and layered retrieval. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct SearchArgs { - pub query: String, - pub thread: Option<String>, - pub scope: Option<String>, - pub limit: Option<usize>, + pub query: String, // Required: Search query + pub recursive: Option<bool>, // Default: true + pub return_layers: Option<Vec<String>>, // ["L0", "L1", "L2"] + pub scope: Option<String>, // Search scope URI + pub limit: Option<usize>, // Default: 10 } +``` -#[derive(Debug, Serialize, Deserialize)] +**Response:** +```rust pub struct SearchResponse { pub query: String, pub results: Vec<SearchResult>, - pub count: usize, + pub total: usize, + pub engine_used: String, } -#[derive(Debug, Serialize, Deserialize)] pub struct SearchResult { pub uri: String, - pub snippet: String, pub score: f32, - pub abstract_text: Option<String>, -} - -impl Tool for SearchTool { - const NAME: &'static str = "search"; - // ... + pub snippet: String, + pub content: Option<String>, } ``` -#### FindTool +#### FindTool (`"find"`) -查找特定类型的记忆或内容。 +Quick search returning only L0 abstracts. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct FindArgs { - pub query: String, - pub filters: Option<FindFilters>, - pub limit: Option<usize>, + pub query: String, // Required: Search query + pub scope: Option<String>, // Search scope URI + pub limit: Option<usize>, // Default: 10 } +``` -#[derive(Debug, Serialize, Deserialize)] -pub struct FindFilters { - pub dimensions: Option<Vec<String>>, - pub tags: Option<Vec<String>>, - pub date_range: Option<DateRange>, +**Response:** +```rust +pub struct FindResponse { + pub query: String, + pub results: Vec<FindResult>, + pub total: usize, } -impl Tool for FindTool { - const NAME: &'static str = "find"; - // ... +pub struct FindResult { + pub uri: String, + pub score: f32, + pub abstract_text: String, } ``` -### 文件系统工具 +### Filesystem Tools -#### LsTool +#### LsTool (`"ls"`) -列出目录内容。 +List directory contents. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct LsArgs { + pub uri: String, // Default: "cortex://session" + pub recursive: Option<bool>, // Default: false + pub include_abstracts: Option<bool>, // Default: false +} +``` + +**Response:** +```rust +pub struct LsResponse { pub uri: String, - pub recursive: Option<bool>, - pub include_abstracts: Option<bool>, + pub entries: Vec<LsEntry>, + pub total: usize, } -impl Tool for LsTool { - const NAME: &'static str = "ls"; - // ... +pub struct LsEntry { + pub name: String, + pub uri: String, + pub is_directory: bool, + pub size: Option<u64>, + pub abstract_text: Option<String>, } ``` -#### ExploreTool +#### ExploreTool (`"explore"`) -探索结构化的记忆内容。 +Intelligent memory exploration. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct ExploreArgs { - pub uri: String, - pub depth: Option<usize>, - pub filters: Option<ExploreFilters>, + pub query: String, // Required: Exploration query + pub start_uri: Option<String>, // Default: "cortex://session" + pub max_depth: Option<usize>, // Default: 3 + pub return_layers: Option<Vec<String>>, // Default: ["L0"] } +``` -impl Tool for ExploreTool { - const NAME: &'static str = "explore"; - // ... +**Response:** +```rust +pub struct ExploreResponse { + pub query: String, + pub exploration_path: Vec<String>, + pub matches: Vec<ExploreMatch>, + pub total_explored: usize, + pub total_matches: usize, } ``` -#### StoreTool +### Storage Tool + +#### StoreTool (`"store"`) -存储新记忆。 +Store content with automatic L0/L1 layer generation. +**Parameters:** ```rust -#[derive(Debug, Serialize, Deserialize)] pub struct StoreArgs { - pub content: String, - pub thread_id: Option<String>, - pub role: Option<String>, - pub metadata: Option<serde_json::Value>, + pub content: String, // Required: Content to store + pub thread_id: String, // Default: "" + pub metadata: Option<Value>, // Optional metadata + pub auto_generate_layers: Option<bool>, // Default: true + pub scope: String, // "session", "user", or "agent" + pub user_id: Option<String>, // Required for user scope + pub agent_id: Option<String>, // Required for agent scope } +``` -impl Tool for StoreTool { - const NAME: &'static str = "store"; - // ... +**Response:** +```rust +pub struct StoreResponse { + pub uri: String, + pub layers_generated: Vec<String>, + pub success: bool, } ``` -## 🛠️ Agent 集成 +## 🔧 Rig Framework Integration + +### Tool Trait Implementation + +Each tool implements the `rig::tool::Tool` trait: + +```rust +impl Tool for AbstractTool { + const NAME: &'static str = "abstract"; + + type Error = ToolsError; + type Args = AbstractArgs; + type Output = AbstractResponse; + + fn definition(&self, _prompt: String) -> impl Future<Output = ToolDefinition> + Send + Sync { + async { + ToolDefinition { + name: Self::NAME.to_string(), + description: "...".to_string(), + parameters: json!({ /* JSON Schema */ }), + } + } + } + + async fn call(&self, args: Self::Args) -> Result<Self::Output, Self::Error> { + Ok(self.operations.get_abstract(&args.uri).await?) + } +} +``` -### 完整示例 +### Agent Integration Example ```rust -use rig::providers::openai::{Client, completion::CompletionModel}; +use rig::providers::openai::{Client, GPT_4O_MINI}; use cortex_mem_rig::MemoryTools; -use cortex_mem_tools::MemoryOperations; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { - // 初始化 OpenAI 客户端 - let openai_client = Client::from_env()?; + // Initialize OpenAI client + let client = Client::from_env(); - // 创建记忆操作 - let operations = Arc::new(MemoryOperations::from_data_dir("./cortex-data").await?); - - // 创建工具集 - let memory_tools = MemoryTools::new(operations); + // Create memory tools + let memory_tools = create_memory_tools_with_tenant_and_vector( + "./cortex-data", + "default", + llm_client, + "http://localhost:6333", + "cortex_memories", + "https://api.openai.com/v1", + "your-key", + "text-embedding-3-small", + Some(1536), + None, + ).await?; - // 创建 Agent - let agent = openai_client - .completion_model(CompletionModel::Gpt4Omini) - .agent("记忆助手") - .preamble("你是一个具有长期记忆的 AI 助手。你可以存储和检索用户信息。") + // Create agent with tools + let agent = client + .agent(GPT_4O_MINI) + .preamble("You are an AI assistant with persistent memory capabilities.") .tool(memory_tools.abstract_tool()) .tool(memory_tools.overview_tool()) .tool(memory_tools.read_tool()) @@ -323,147 +418,103 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> { .tool(memory_tools.store_tool()) .build(); - // 对话示例 + // Use the agent let response = agent.prompt( - "请先搜索关于用户偏好的信息，然后存储用户喜欢使用深色主题的偏好。" + "Search for user preferences and store that they like dark theme." ).await?; - println!("Agent 响应: {}", response); + println!("Agent response: {}", response); Ok(()) } ``` -### 链式工具调用 - -```rust -// Agent 会自动进行链式调用 -let response = agent.prompt( - "1. 搜索用户之前关于编程语言偏好的讨论\n\ - 2. 获取最相关讨论的概览\n\ - 3. 如果需要，读取完整内容\n\ - 4. 基于结果提供个性化建议" -).await?; -``` +## 🎯 Best Practices -## 🎯 最佳实践 +### Tiered Access Pattern -### 分层访问模式 +1. **Use `abstract` first** for quick relevance checking +2. **Use `overview` if relevant** for more context +3. **Use `read` only when necessary** for complete content -1. **首先使用 abstract()** 快速判断相关性 -2. **如果相关，使用 overview()** 获取更多上下文 -3. **仅在必要时使用 read()** 获取完整内容 +### Search Optimization ```rust -// Agent 的内部思考模式可能如下： -// 1. 用户询问关于 Rust 的问题 -// 2. 搜索 "Rust programming" -// 3. 对每个结果使用 abstract() 检查相关性 -// 4. 对相关的使用 overview() 获取更多上下文 -// 5. 对最终需要的文档使用 read() 获取完整内容 -``` - -### 搜索优化 - -```rust -// 限定搜索范围 -agent.prompt("在 'tech-discussions' 会话中搜索 Rust 相关内容").await?; +// Limit search scope for better performance +agent.prompt("Search 'error handling' in session 'rust-discussion'").await?; -// 使用精确查询 -agent.prompt("查找与 'async/await' 相关的具体实现示例").await?; +// Use find for quick lookups (returns only L0 abstracts) +agent.prompt("Find memories about 'OAuth' and show abstracts").await?; -// 结合分层访问 +// Combine with tiered access agent.prompt( - "搜索 '错误处理'，对前3个结果获取摘要，然后对最相关的获取概览" + "Search 'async programming', get abstracts for top 3, then read the most relevant one" ).await?; ``` -## 🔧 高级配置 - -### 自定义工具 +### Memory Storage ```rust -use cortex_mem_rig::tools::AbstractTool; - -impl AbstractTool { - pub fn with_custom_token_limit(operations: Arc<MemoryOperations>, limit: usize) -> Self { - // 自定义 token 限制 - Self { operations, token_limit: Some(limit) } - } -} -``` +// Store in session scope (default) +agent.prompt("Store 'User is learning Rust async' in current session").await?; -### 工具组合 - -```rust -// 创建专门的工具组合 -let retrieval_tools = MemoryToolsBuilder::new(operations) - .with_tiered_access() // L0, L1, L3 工具 - .with_search() // 搜索工具 - .with_filesystem() // 文件系统工具 - .build(); - -let write_tools = MemoryToolsBuilder::new(operations) - .with_store() // 存储工具 - .with_search() // 用于验证的搜索 - .build(); +// Store in user scope for long-term memory +agent.prompt("Store 'User prefers dark mode' as a user preference").await?; ``` -## 🧪 测试 +## 🧪 Testing ```bash -# 运行 Rig 集成测试 +# Run Rig integration tests cargo test -p cortex-mem-rig -# 运行工具测试 -cargo test -p cortex-mem-rig tools - -# 运行端到端测试 -cargo test -p cortex-mem-rig e2e +# Run all tests +cargo test --all ``` -## 🚨 常见问题 +## 🚨 Common Issues -### 1. 工具调用失败 +### Tool Call Failed -确保： -- Cortex Memory 核心正确初始化 -- 数据目录具有写权限 -- 搜索索引已建立 +Ensure: +- Cortex Memory Core is properly initialized +- Data directory has write permissions +- Search index is built -### 2. 抽象内容为空 +### Empty Abstract Content -可能原因： -- 文件不存在 -- 内容过短无法生成摘要 -- LLM 服务不可用 +Possible causes: +- File does not exist +- Content too short to generate summary +- LLM service unavailable -### 3. 搜索结果不准确 +### Inaccurate Search Results -优化方法： -- 使用更精确的查询 -- 限定搜索范围 -- 使用 find 工具而非 search +Optimization tips: +- Use more specific queries +- Limit search scope +- Use `search` instead of `find` for comprehensive results -## 🛣️ 路线图 +## 📦 Dependencies -- [ ] 流式访问工具（适用于大文件） -- [ ] 缓存层优化 -- [ ] 工具调用统计 -- [ ] 自动工具选择 -- [ ] 多模态记忆支持 +- `cortex-mem-tools` - High-level memory operations +- `cortex-mem-core` - Core library +- `rig-core` - Rig AI framework +- `tokio` - Async runtime +- `serde` / `serde_json` - Serialization +- `anyhow` / `thiserror` - Error handling -## 📄 许可证 +## 📄 License -MIT 许可证 - 详见 [LICENSE](../../LICENSE) 文件 +MIT License - see the [LICENSE](../../LICENSE) file for details. -## 🔗 相关资源 +## 🔗 Related Resources -- [Cortex Memory 核心](../cortex-mem-core/README.md) -- [Cortex Memory 工具](../cortex-mem-tools/README.md) -- [Rig 框架](https://github.com/coreylowman/rig) -- [Rig 文档](https://docs.rs/rig/) +- [Cortex Memory Core](../cortex-mem-core/README.md) +- [Cortex Memory Tools](../cortex-mem-tools/README.md) +- [Rig Framework](https://github.com/0xPlaygrounds/rig) +- [Rig Documentation](https://docs.rs/rig/) --- -**Built with ❤️ using Rust and Rig AI Framework** \ No newline at end of file +**Built with ❤️ using Rust and Rig AI Framework** diff --git a/cortex-mem-tools/Cargo.toml b/cortex-mem-tools/Cargo.toml index d3b834f..721db1d 100644 --- a/cortex-mem-tools/Cargo.toml +++ b/cortex-mem-tools/Cargo.toml @@ -4,7 +4,7 @@ version.workspace = true edition.workspace = true authors.workspace = true license.workspace = true -description = "High-level tools and utilities for Cortex-Mem V2" +description = "High-level tools and utilities for Cortex Memory Integration" [dependencies] # Local dependencies diff --git a/cortex-mem-tools/README.md b/cortex-mem-tools/README.md index 870b967..ac44815 100644 --- a/cortex-mem-tools/README.md +++ b/cortex-mem-tools/README.md @@ -6,24 +6,69 @@ Cortex Memory Tools implements: - High-level `MemoryOperations` interface for unified access to Cortex Memory -- **Tiered Access**: L0 (Abstract), L1 (Overview), L2 (Full Content) +- **Tiered Access**: L0 (Abstract ~100 tokens), L1 (Overview ~2000 tokens), L2 (Full Content) - Advanced automation with event-driven processing - Model Context Protocol (MCP) tool definitions -- Utility functions for memory management - Type-safe error handling and comprehensive types ## 🏗️ Core Components ### MemoryOperations -The primary interface for working with Cortex Memory. It requires: -- LLM client for layer generation -- Vector search engine for semantic search -- Embedding client for vectorization +The primary interface for working with Cortex Memory: + +``` +MemoryOperations + | + +---> Tiered Access (L0/L1/L2) + | | + | +---> get_abstract() -> AbstractResponse + | +---> get_overview() -> OverviewResponse + | +---> get_read() -> ReadResponse + | + +---> Search Operations + | | + | +---> search() -> SearchResponse + | +---> find() -> FindResponse + | + +---> Filesystem Operations + | | + | +---> ls() -> LsResponse + | +---> explore() -> ExploreResponse + | + +---> Storage Operations + | | + | +---> store() -> StoreResponse + | + +---> Session Management + | | + | +---> add_message() + | +---> list_sessions() + | +---> get_session() + | +---> close_session() + | + +---> Automation + | + +---> ensure_all_layers() + +---> index_all_files() +``` + +## 🚀 Quick Start + +### Installation + +```toml +[dependencies] +cortex-mem-tools = { path = "../cortex-mem-tools" } +cortex-mem-core = { path = "../cortex-mem-core" } +tokio = { version = "1", features = ["full"] } +``` + +### Basic Usage ```rust use cortex_mem_tools::MemoryOperations; -use cortex_mem_core::llm::{LLMClient, LLMClientImpl, LLMConfig}; +use cortex_mem_core::llm::{LLMClientImpl, LLMConfig}; use std::sync::Arc; #[tokio::main] @@ -58,18 +103,29 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> { "user", "How do I reset my password?" ).await?; - - // Read file content (L2) - let content = ops.read_file("cortex://session/tech-support/timeline/...").await?; + println!("Message ID: {}", msg_id); // Get abstract (L0) - quick relevance check - let abstract_result = ops.get_abstract("cortex://session/tech-support/...").await?; + let abstract_result = ops.get_abstract(&format!( + "cortex://session/tech-support/timeline/{}.md", + msg_id + )).await?; println!("Abstract: {}", abstract_result.abstract_text); // Get overview (L1) - partial context - let overview = ops.get_overview("cortex://session/tech-support/...").await?; + let overview = ops.get_overview(&format!( + "cortex://session/tech-support/timeline/{}.md", + msg_id + )).await?; println!("Overview: {}", overview.overview_text); + // Read file content (L2) + let content = ops.read_file(&format!( + "cortex://session/tech-support/timeline/{}.md", + msg_id + )).await?; + println!("Content: {}", content); + // List sessions let sessions = ops.list_sessions().await?; for session in sessions { @@ -82,64 +138,58 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> { ### Tiered Access (OpenViking Style) -The library implements a three-tier access pattern for efficient memory retrieval: - | Layer | Size | Purpose | Method | |-------|------|---------|--------| | **L0 Abstract** | ~100 tokens | Quick relevance judgment | `get_abstract()` | | **L1 Overview** | ~2000 tokens | Partial context understanding | `get_overview()` | | **L2 Full** | Complete content | Deep analysis and processing | `read_file()` / `get_read()` | -### Automation System - -MemoryOperations includes built-in automation: - -- **Auto Indexing**: Messages are automatically indexed for vector search -- **Auto Extraction**: Memories are extracted when sessions are closed -- **Event-Driven**: Uses EventBus for real-time processing +### Tool-Based Operations ```rust -// Automation is built into MemoryOperations::new() -// No additional configuration needed - -// Access the auto extractor for manual extraction -if let Some(extractor) = ops.auto_extractor() { - extractor.extract_session("tech-support").await?; +use cortex_mem_tools::{MemoryOperations, SearchArgs, LsArgs, StoreArgs}; + +// Search with typed args +let search_result = ops.search(SearchArgs { + query: "password reset".to_string(), + recursive: Some(true), + return_layers: Some(vec!["L0".to_string(), "L1".to_string()]), + scope: Some("cortex://session".to_string()), + limit: Some(10), +}).await?; + +for result in &search_result.results { + println!("URI: {} (score: {:.2})", result.uri, result.score); } -``` - -### MCP Integration - -The library provides tool definitions for Model Context Protocol: -```rust -use cortex_mem_tools::mcp::{get_mcp_tool_definitions, get_mcp_tool_definition}; +// List directory with abstracts +let ls_result = ops.ls(LsArgs { + uri: "cortex://session".to_string(), + recursive: Some(false), + include_abstracts: Some(true), +}).await?; -// Get all available MCP tool definitions -let tools = get_mcp_tool_definitions(); -for tool in &tools { - println!("Available tool: {} - {}", tool.name, tool.description); +for entry in &ls_result.entries { + println!("{}: {}", entry.name, entry.abstract_text.as_ref().unwrap_or(&"".to_string())); } -// Get a specific tool definition -if let Some(tool) = get_mcp_tool_definition("search") { - println!("Search tool: {:?}", tool.input_schema); -} +// Store with auto layer generation +let store_result = ops.store(StoreArgs { + content: "User prefers dark mode and vim keybindings".to_string(), + thread_id: "user-prefs".to_string(), + metadata: None, + auto_generate_layers: Some(true), + scope: "user".to_string(), + user_id: Some("user-123".to_string()), + agent_id: None, +}).await?; + +println!("Stored at: {}", store_result.uri); ``` -Available MCP tools: -- `abstract` - Get L0 abstract -- `overview` - Get L1 overview -- `read` - Get L2 full content -- `search` - Intelligent search with multiple engines -- `find` - Quick search returning L0 abstracts -- `ls` - List directory contents -- `explore` - Intelligently explore memory space -- `store` - Store content with automatic layer generation - ## 📚 API Reference -### MemoryOperations +### MemoryOperations Constructor ```rust impl MemoryOperations { @@ -156,115 +206,244 @@ impl MemoryOperations { embedding_dim: Option<usize>, user_id: Option<String>, ) -> Result<Self> - - // Accessors - pub fn filesystem(&self) -> &Arc<CortexFilesystem> - pub fn vector_engine(&self) -> &Arc<VectorSearchEngine> - pub fn session_manager(&self) -> &Arc<RwLock<SessionManager>> - pub fn auto_extractor(&self) -> Option<&Arc<AutoExtractor>> - - // Session Management - pub async fn add_message(&self, thread_id: &str, role: &str, content: &str) -> Result<String> - pub async fn list_sessions(&self) -> Result<Vec<SessionInfo>> - pub async fn get_session(&self, thread_id: &str) -> Result<SessionInfo> - pub async fn close_session(&self, thread_id: &str) -> Result<()> - - // Tiered Access (L0/L1/L2) - pub async fn get_abstract(&self, uri: &str) -> Result<AbstractResponse> - pub async fn get_overview(&self, uri: &str) -> Result<OverviewResponse> - pub async fn get_read(&self, uri: &str) -> Result<ReadResponse> - - // File Operations - pub async fn read_file(&self, uri: &str) -> Result<String> - pub async fn list_files(&self, uri: &str) -> Result<Vec<String>> - pub async fn delete(&self, uri: &str) -> Result<()> - pub async fn exists(&self, uri: &str) -> Result<bool> - - // Tool-based Operations (using typed args) - pub async fn search(&self, args: SearchArgs) -> Result<SearchResponse> - pub async fn find(&self, args: FindArgs) -> Result<FindResponse> - pub async fn ls(&self, args: LsArgs) -> Result<LsResponse> - pub async fn explore(&self, args: ExploreArgs) -> Result<ExploreResponse> - pub async fn store(&self, args: StoreArgs) -> Result<StoreResponse> } ``` -### Type Definitions +### Accessor Methods + +| Method | Return Type | Description | +|--------|-------------|-------------| +| `filesystem()` | `&Arc<CortexFilesystem>` | Get underlying filesystem | +| `vector_engine()` | `&Arc<VectorSearchEngine>` | Get vector search engine | +| `session_manager()` | `&Arc<RwLock<SessionManager>>` | Get session manager | +| `auto_extractor()` | `Option<&Arc<AutoExtractor>>` | Get auto extractor | +| `layer_generator()` | `Option<&Arc<LayerGenerator>>` | Get layer generator | +| `auto_indexer()` | `Option<&Arc<AutoIndexer>>` | Get auto indexer | + +### Session Management + +| Method | Parameters | Description | +|--------|------------|-------------| +| `add_message()` | `thread_id, role, content` | Add message to session | +| `list_sessions()` | - | List all sessions | +| `get_session()` | `thread_id` | Get session info | +| `close_session()` | `thread_id` | Close a session | + +### Tiered Access (L0/L1/L2) + +| Method | Parameters | Returns | +|--------|------------|---------| +| `get_abstract()` | `uri: &str` | `AbstractResponse` | +| `get_overview()` | `uri: &str` | `OverviewResponse` | +| `get_read()` | `uri: &str` | `ReadResponse` | + +### File Operations + +| Method | Parameters | Description | +|--------|------------|-------------| +| `read_file()` | `uri` | Read file content | +| `list_files()` | `uri` | List files in directory | +| `delete()` | `uri` | Delete file/directory | +| `exists()` | `uri` | Check existence | + +### Tool-Based Operations + +| Method | Parameters | Returns | +|--------|------------|---------| +| `search()` | `SearchArgs` | `SearchResponse` | +| `find()` | `FindArgs` | `FindResponse` | +| `ls()` | `LsArgs` | `LsResponse` | +| `explore()` | `ExploreArgs` | `ExploreResponse` | +| `store()` | `StoreArgs` | `StoreResponse` | + +### Automation Methods + +| Method | Return Type | Description | +|--------|-------------|-------------| +| `ensure_all_layers()` | `GenerationStats` | Generate missing L0/L1 layers | +| `index_all_files()` | `SyncStats` | Index all files to vector DB | + +## 📖 Type Definitions + +### Tiered Access Responses ```rust -// Tiered access responses pub struct AbstractResponse { pub uri: String, pub abstract_text: String, - pub layer: String, // "L0" + pub layer: String, // "L0" pub token_count: usize, } pub struct OverviewResponse { pub uri: String, pub overview_text: String, - pub layer: String, // "L1" + pub layer: String, // "L1" pub token_count: usize, } pub struct ReadResponse { pub uri: String, pub content: String, - pub layer: String, // "L2" + pub layer: String, // "L2" pub token_count: usize, pub metadata: Option<FileMetadata>, } +``` -// Search types +### Search Types + +```rust pub struct SearchArgs { pub query: String, - pub recursive: Option<bool>, - pub return_layers: Option<Vec<String>>, // ["L0", "L1", "L2"] + pub recursive: Option<bool>, // Default: true + pub return_layers: Option<Vec<String>>, // ["L0", "L1", "L2"] + pub scope: Option<String>, // Search scope URI + pub limit: Option<usize>, // Default: 10 +} + +pub struct SearchResponse { + pub query: String, + pub results: Vec<SearchResult>, + pub total: usize, + pub engine_used: String, +} + +pub struct SearchResult { + pub uri: String, + pub score: f32, + pub snippet: String, + pub content: Option<String>, +} + +pub struct FindArgs { + pub query: String, pub scope: Option<String>, pub limit: Option<usize>, } +pub struct FindResponse { + pub query: String, + pub results: Vec<FindResult>, + pub total: usize, +} +``` + +### Filesystem Types + +```rust +pub struct LsArgs { + pub uri: String, // Default: "cortex://session" + pub recursive: Option<bool>, // Default: false + pub include_abstracts: Option<bool>, // Default: false +} + +pub struct LsResponse { + pub uri: String, + pub entries: Vec<LsEntry>, + pub total: usize, +} + +pub struct ExploreArgs { + pub query: String, + pub start_uri: Option<String>, // Default: "cortex://session" + pub max_depth: Option<usize>, // Default: 3 + pub return_layers: Option<Vec<String>>, // Default: ["L0"] +} + +pub struct ExploreResponse { + pub query: String, + pub exploration_path: Vec<String>, + pub matches: Vec<ExploreMatch>, + pub total_explored: usize, + pub total_matches: usize, +} +``` + +### Storage Types + +```rust pub struct StoreArgs { pub content: String, - pub thread_id: String, + pub thread_id: String, // Default: "" pub metadata: Option<Value>, - pub auto_generate_layers: Option<bool>, - pub scope: String, // "session", "user", or "agent" - pub user_id: Option<String>, - pub agent_id: Option<String>, + pub auto_generate_layers: Option<bool>, // Default: true + pub scope: String, // "session", "user", or "agent" + pub user_id: Option<String>, // Required for user scope + pub agent_id: Option<String>, // Required for agent scope +} + +pub struct StoreResponse { + pub uri: String, + pub layers_generated: Vec<String>, + pub success: bool, +} +``` + +### Session Info + +```rust +pub struct SessionInfo { + pub thread_id: String, + pub status: String, + pub message_count: usize, + pub created_at: String, + pub updated_at: String, } ``` -## 🧱 Architecture +## 🔌 MCP Integration + +The library provides tool definitions for Model Context Protocol: + +```rust +use cortex_mem_tools::mcp::{get_mcp_tool_definitions, get_mcp_tool_definition}; +// Get all available MCP tool definitions +let tools = get_mcp_tool_definitions(); +for tool in &tools { + println!("Tool: {} - {}", tool.name, tool.description); +} + +// Get a specific tool definition +if let Some(tool) = get_mcp_tool_definition("search") { + println!("Search tool schema: {:?}", tool.input_schema); +} ``` -┌─────────────────────────────────────┐ -│ Application Layer │ -├─────────────────────────────────────┤ -│ MemoryOperations API │ -│ ┌──────────┬──────────┬────────┐ │ -│ │ L0:Abs │ L1:Over │ L2:Full│ │ -│ └──────────┴──────────┴────────┘ │ -├─────────────────────────────────────┤ -│ Automation Layer │ -│ ┌─────────────┬────────────────┐ │ -│ │ AutoIndexer │ AutoExtractor │ │ -│ └─────────────┴────────────────┘ │ -├─────────────────────────────────────┤ -│ Event System │ -│ ┌─────────────┬────────────────┐ │ -│ │ EventBus │ EventListeners │ │ -│ └─────────────┴────────────────┘ │ -├─────────────────────────────────────┤ -│ Core Layer │ -│ CortexFilesystem│SessionManager │ -│ LayerManager │VectorSearchEngine│ -└─────────────────────────────────────┘ + +### Available MCP Tools + +| Tool | Description | Required Params | Optional Params | +|------|-------------|-----------------|-----------------| +| `abstract` | Get L0 abstract | `uri` | - | +| `overview` | Get L1 overview | `uri` | - | +| `read` | Get L2 full content | `uri` | - | +| `search` | Intelligent search | `query` | `recursive, return_layers, scope, limit` | +| `find` | Quick search (L0 only) | `query` | `scope, limit` | +| `ls` | List directory | `uri` | `recursive, include_abstracts` | +| `explore` | Intelligent exploration | `query` | `start_uri, max_depth, return_layers` | +| `store` | Store with auto layers | `content, thread_id` | `metadata, auto_generate_layers, scope, user_id, agent_id` | + +## ⚠️ Error Handling + +All operations return `Result<T, ToolsError>`: + +```rust +pub enum ToolsError { + InvalidInput(String), // Invalid input provided + Runtime(String), // Runtime error during operation + NotFound(String), // Memory not found + Custom(String), // Custom error + Serialization(Error), // Serde JSON error + Core(Error), // Core library error + Io(Error), // IO error +} + +pub type Result<T> = std::result::Result<T, ToolsError>; ``` ## 📦 Dependencies -This crate depends on: - `cortex-mem-core` - Core library with all memory operations - `tokio` - Async runtime - `serde` / `serde_json` - Serialization @@ -276,26 +455,17 @@ This crate depends on: ## 🧪 Testing -Run tests with all features: - ```bash +# Run tests cargo test -p cortex-mem-tools -``` - -## 🔍 Error Handling -All operations return `Result<T, ToolsError>` where `ToolsError` includes: - -- Configuration errors -- Filesystem errors -- Session errors -- Search errors -- Automation errors -- MCP tool errors +# Run specific tests +cargo test -p cortex-mem-tools core_functionality +``` ## 📄 License -MIT License - see the [`LICENSE`](../../LICENSE) file for details. +MIT License - see the [LICENSE](../../LICENSE) file for details. ## 🤝 Contributing @@ -309,8 +479,11 @@ Contributions are welcome! Please: ## 🔗 Related Crates - [`cortex-mem-core`](../cortex-mem-core/) - Core library -- [`cortex-mem-mcp`](../cortex-mem-mcp/) - MCP server -- [`cortex-mem-rig`](../cortex-mem-rig/) - Rig integration +- [`cortex-mem-mcp`](../cortex-mem-mcp/) - MCP server implementation +- [`cortex-mem-rig`](../cortex-mem-rig/) - Rig framework integration - [`cortex-mem-service`](../cortex-mem-service/) - HTTP REST API +- [`cortex-mem-cli`](../cortex-mem-cli/) - Command-line interface --- + +**Built with ❤️ using Rust** \ No newline at end of file