Cortex Memory
English
|
中文
🧠 为构建智能、上下文感知应用而生的AI原生内存框架 🧠
基于Rust构建，Cortex Memory是一个高性能、持久化、智能的长期内存系统，赋予您的OpenClaw等各类自主AI代理跨会话记住、学习和个性化交互的能力。
# 👋 什么是 Cortex Memory？
**Cortex Memory** 是一个完整的、生产就绪的框架，为您的AI应用程序提供长期记忆能力。它超越了简单的聊天历史，提供了一个具有**分层三级内存架构**(L0 抽象层 → L1 概览层 → L2 详细层)的智能内存系统，能够自动提取、组织和优化信息，使您的AI代理更智能、更具个性化。
Cortex Memory 使用复杂的流水线来处理和管理内存，核心是**混合存储架构**，结合了**虚拟文件系统**的持久性和基于向量的**语义搜索**。
| 高效能 **渐进式记忆披露** 搜索架构 | 基于 **虚拟文件系统** 的记忆架构 | **高精准** 记忆检索召回能力 |
| :--- | :--- | :--- |
|  | |  |
**Cortex Memory** 使用**虚拟文件系统**方法组织数据,采用 `cortex://` URI 方案：
```
# 基本结构
cortex://{维度}/{路径}
# 维度说明
session/ - 会话记忆（对话历史、时间线）
user/ - 用户记忆（偏好、实体、事件）
agent/ - Agent记忆（案例、技能）
resources/ - 知识库资源
# 示例
cortex://session/{session_id}/timeline/{date}/{time}.md
cortex://user/preferences/{name}.md
cortex://agent/cases/{case_id}.md
cortex://resources/{resource_name}/
```
**高性能、低Token消耗的Memory解决方案，相比OpenClaw有显著优势，最高节约95%的token费用**
LoCoMo Benchmark每题平均 Token 成本对比
| 系统 | 每题输入 Tokens |
|------|:--------------:|
| **Cortex Memory（intent ON）** | **1,964** |
| Cortex Memory（intent OFF） | 1,874 |
| OpenClaw + OpenViking Plugin (-memory-core) | 2,769 |
| OpenClaw + OpenViking Plugin (+memory-core) | 1,363 |
| OpenClaw (memory-core 内置) | 15,982 |
| OpenClaw + LanceDB (-memory-core) | 33,490 |
> Cortex Memory 每题 效果表现与 OpenViking Plugin (+memory-core) 最强配置相当，token 成本远低于 LanceDB 和 memory-core 内置方案。
# 😺 为什么使用 Cortex Memory？
将您的无状态AI转变为智能的、上下文感知的合作伙伴。
| 使用 Cortex Memory 之前 |
使用 Cortex Memory 之后 |
|
无状态 AI
- 每次会话后遗忘用户详情
- 缺乏个性化和上下文
- 重复提问和建议
- 仅限于短期对话历史
- 感觉机械且缺乏个性
|
带有 Cortex Memory 的智能AI
- 记住用户偏好和历史
- 提供深度个性化交互
- 随时间学习和适应
- 跨多个对话维持上下文
- 建立融洽关系，感觉像真正的助手
|
🌟 适用于：
- 构建LLM驱动的聊天机器人和代理的开发者。
- 创建个性化AI助手的团队。
- 需要内存骨干的开源项目。
- 任何想构建真正智能AI应用的人！
❤️ 喜欢 Cortex Memory？给它点个星 🌟 或 [赞助我](https://github.com/sponsors/sopaco)！❤️
# 🌠 功能与能力
- 基于文件系统的存储： 内存内容使用`cortex://`虚拟URI方案存储为markdown文件，支持版本控制兼容性和可移植性。
- 智能内存提取： 使用LLM驱动分析和置信度评分，自动从对话中提取结构化内存（事实、决策、实体）。
- 基于向量的语义搜索： 通过Qdrant进行高性能相似性搜索，跨维度（用户/代理/会话）进行元数据过滤，使用加权评分。
- 多模态访问： 通过REST API、CLI、MCP协议或直接Rust库集成进行交互。
- 三级内存层次结构： 渐进式披露系统（L0 抽象 → L1 概览 → L2 详细）通过懒生成优化LLM上下文窗口使用。
- 会话管理： 跟踪对话时间线、参与者和消息历史，具有自动索引和事件驱动处理。
- 多租户支持： 通过租户感知集合命名，在单个部署中为不同用户和代理提供隔离的内存空间。
- 事件驱动自动化： 文件监视器和自动索引器用于后台处理、同步和配置文件丰富。
- LLM结果缓存： 智能缓存采用LRU淘汰和TTL过期机制，减少50-75%的冗余LLM API调用，级联层防抖可减少70-90%的层更新调用。
- 增量记忆更新： 引入了事件驱动的增量更新系统（`MemoryEventCoordinator`、`CascadeLayerUpdater`），在记忆变更时自动保持 L0/L1 层级同步。
- 记忆遗忘机制： 引入了基于 Ebbinghaus 遗忘曲线的 `MemoryCleanupService`——自动归档或删除低强度记忆，控制长期运行 Agent 的存储空间膨胀。
- 代理框架集成： 内置支持Rig框架和模型上下文协议（MCP）。
- Web仪表板： Svelte 5 SPA（Insights）用于监控、租户管理和语义搜索可视化。
# 🧠 工作原理
Cortex Memory使用复杂的流水线来处理和管理内存，核心是**混合存储架构**，结合了**虚拟文件系统**的持久性和基于向量的**语义搜索**。
```mermaid
flowchart TB
subgraph Input["输入层"]
User[用户消息]
Agent[代理消息]
CLI[CLI命令]
API[REST API]
MCP[MCP协议]
end
subgraph Core["核心引擎 (cortex-mem-core)"]
Session[会话管理器]
Extractor[内存提取器]
Indexer[自动索引器]
Search[向量搜索引擎]
end
subgraph Storage["存储层"]
FS[(文件系统
cortex:// URI)]
Qdrant[(Qdrant
向量索引)]
end
subgraph External["外部服务"]
LLM[LLM提供商
提取与分析]
Embed[嵌入API
向量生成]
end
User --> Session
Agent --> Session
CLI --> Core
API --> Core
MCP --> Core
Session -->|存储消息| FS
Session -->|触发提取| Extractor
Extractor -->|分析内容| LLM
Extractor -->|存储内存| FS
Indexer -->|监视变更| FS
Indexer -->|生成嵌入| Embed
Indexer -->|索引向量| Qdrant
Search -->|查询嵌入| Embed
Search -->|向量搜索| Qdrant
Search -->|检索内容| FS
```
## 内存架构
Cortex Memory使用**虚拟文件系统**方法组织数据，采用`cortex://` URI方案：
```
cortex://{维度}/{范围}/{类别}/{ID}
```
- **维度**：`user`、`agent`、`session`或`resources`
- **范围**：租户或标识符
- **类别**：`memories`、`profiles`、`entities`、`sessions`等
- **ID**：唯一内存标识符
## 三级内存层次结构
Cortex Memory实现了带有三个抽象层的**渐进式披露**系统：
| 层级 | 目的 | 令牌使用 | 用例 |
|-------|---------|-------------|----------|
| **L0 (抽象层)** | 快速定位，粗粒度候选选择 | ~100 令牌 | 初步筛选（20%权重） |
| **L1 (概览层)** | 带有关键点和实体的结构化摘要 | ~500-2000 令牌 | 上下文细化（30%权重） |
| **L2 (详细层)** | 完整对话内容 | 可变 | 精确匹配（50%权重） |
这种分层方法通过仅加载必要的细节级别来优化LLM上下文窗口使用。搜索引擎使用**加权评分**结合所有三个层次`L0/L1/L2`。
# 🌐 Cortex Memory 生态系统
Cortex Memory是一个由多个crate组成的模块化系统，每个crate都有特定用途。这种设计提供了灵活性和关注点分离。
```mermaid
graph TD
subgraph "用户界面"
CLI["cortex-mem-cli
终端界面"]
Insights["cortex-mem-insights
Web仪表板"]
end
subgraph "API与集成"
Service["cortex-mem-service
REST API服务器"]
MCP["cortex-mem-mcp
MCP服务器"]
Rig["cortex-mem-rig
Rig框架"]
end
subgraph "核心引擎"
Core["cortex-mem-core
业务逻辑"]
Tools["cortex-mem-tools
代理工具"]
end
subgraph "外部服务"
VectorDB[("Qdrant
向量数据库")]
LLM[("LLM提供商
OpenAI/Azure/本地")]
end
%% 定义依赖关系
Insights -->|REST API| Service
CLI --> Core
Service --> Core
MCP --> Tools
Rig --> Tools
Tools --> Core
Core --> VectorDB
Core --> LLM
```
- `cortex-mem-core`：系统的核心。包含文件系统抽象（`cortex://` URI）、LLM客户端包装器、嵌入生成、Qdrant集成、会话管理、层生成（L0/L1/L2）、提取引擎、搜索引擎和自动化编排器的业务逻辑，以及 增量更新系统（`MemoryEventCoordinator`、`CascadeLayerUpdater`、`LlmResultCache`、`IncrementalMemoryUpdater`）和 遗忘机制（`MemoryCleanupService`）。
- `cortex-mem-service`：高性能REST API服务器（基于Axum），通过`/api/v2/*`端点暴露所有内存操作，默认端口 8085。
- `cortex-mem-cli`：二进制名为 `cortex-mem` 的命令行工具，供开发人员和管理员直接与内存存储交互。
- `cortex-mem-insights`：纯前端Svelte 5 SPA，用于通过Web界面进行监控、分析和内存管理。
- `cortex-mem-mcp`：模型上下文协议服务器，用于与AI助手（Claude Desktop、Cursor等）集成。
- `cortex-mem-rig`：与rig-core代理框架的集成层，用于工具注册。
- `cortex-mem-tools`：用于代理集成的MCP工具模式和操作包装器。
- `cortex-mem-config`：配置管理模块，处理TOML加载、环境变量解析和租户特定覆盖。
# 🖼️ 可观察性仪表板
Cortex Memory包含一个强大的基于Web的仪表板（`cortex-mem-insights`），提供实时监控、分析和管理能力。该仪表板是一个纯前端Svelte 5 SPA，连接到`cortex-mem-service` REST API。
交互式仪表板： 租户概览、系统健康和存储统计一目了然
### 主要功能
- **租户管理**：查看和切换多个具有隔离内存空间的租户
- **内存浏览器**：导航`cortex://`文件系统以查看和管理内存文件
- **语义搜索**：在内存存储中执行自然语言查询
- **健康监控**：实时服务状态和LLM可用性检查
### 运行仪表板
```bash
# 首先启动后端服务
cortex-mem-service --data-dir ./cortex-data --port 8085
# 在另一个终端中，启动insights仪表板
cd cortex-mem-insights
bun install
bun run dev
```
仪表板将在`http://localhost:5173`上可用，并将API请求代理到后端服务。
# 🦞 社区Showcase：MemClaw
**MemClaw** 是一款为 OpenClaw 生态深度定制的记忆增强插件，由本地化运行的 Cortex Memory 引擎驱动。相比 OpenClaw 内置记忆系统，MemClaw 提供更强大的记忆能力，**节省超过 80% 的 token 消耗**，同时保持卓越的记忆准确性、安全性和性能。
## 为什么选择 MemClaw？
| OpenClaw 原生记忆 | MemClaw |
|-------------------|---------|
| 基础记忆存储 | **三层 L0/L1/L2 架构** 实现智能检索 |
| 较高的 token 消耗 | **节省 80%+ token** 通过分层上下文加载 |
| 搜索精度有限 | **向量搜索 + Agentic VFS探索** 灵活应对各类复杂场景 |
## 核心特性
- **🎯 低Token与硬件资源消耗**：由Rust驱动的极致高性能内存组件，渐进式检索架构实现最优上下文加载
- **🔒 完全数据隐私**：所有记忆存储在本地，零云端存储依赖
- **🚀 一键迁移**：从 OpenClaw 原生记忆无缝迁移到 MemClaw
- **⚙️ 便捷配置**：零运行时依赖，一行命令全部搞定安装，只需最简化配置即可使用。
## 可用工具
| 工具 | 用途 |
|------|------|
| `cortex_search` | 跨所有记忆的语义搜索，支持分层检索 |
| `cortex_recall` | 带扩展上下文的记忆召回（摘要 + 完整内容） |
| `cortex_add_memory` | 存储消息以供后续检索 |
| `cortex_close_session` | 关闭会话并触发记忆提取流程 |
| `cortex_migrate` | 从 OpenClaw 原生记忆一键迁移 |
| `cortex_maintenance` | 定期维护（清理、重建索引、层生成） |
## 快速开始
```bash
# 通过 OpenClaw 安装
openclaw plugins install @memclaw/memclaw
```
> **注意**：设置 `memorySearch.enabled: false` 以禁用 OpenClaw 内置记忆系统，改用 MemClaw。
## 文档
详细的配置说明、故障排查和最佳实践，请参阅 [MemClaw README](examples/@memclaw/plugin/README_zh.md)。
---
# 🌟 社区Showcase：Cortex TARS
认识**Cortex TARS** - 一个生产就绪的AI原生TUI（终端用户界面）应用程序，展示了Cortex Memory的真正强大功能。作为"第二大脑"同伴构建，Cortex TARS为您的AI体验带来**听觉存在感**，可以在现实世界中真正听到并记住您的声音，展示了持久内存如何将AI交互从短暂的聊天转变为持久的、智能的伙伴关系。
## Cortex TARS 有何特别之处？
Cortex TARS不仅仅是一个聊天机器人 - 它是一个全面的AI助手平台，利用了Cortex Memory的先进功能：
### 🎭 多代理管理
创建和管理多个AI角色，每个角色都有独特的个性、系统提示和专业知识领域。无论您需要编码助手、创意写作伙伴还是生产力教练，Cortex TARS都能让您同时运行所有这些角色，并保持完全分离。
### 💾 持久角色内存
每个代理都保持自己的长期记忆，从随时间的交互中学习。您的编码助手会记住您的编码风格和偏好；您的写作教练会适应您的声音和目标。无需重复自己 - 每个代理通过每次对话变得更聪明。
### 🔒 内存隔离
先进的内存架构确保代理和用户之间的完全隔离。每个代理的知识库是独立的，防止交叉污染，同时在不同的上下文和用例中实现个性化体验。
### 🎤 实时音频到内存（游戏规则改变者）
**这是Cortex TARS真正发光的地方。** 通过实时设备音频捕获，Cortex TARS可以监听您的对话、会议或讲座，并自动将它们转换为结构化的、可搜索的内存。想象一下，在参加会议时，Cortex TARS静静地捕捉关键见解、决策和行动项 - 全部存储并准备随时检索。不再需要慌乱记笔记或忘记细节！
## 为什么 Cortex TARS 重要
Cortex TARS不仅仅是一个例子 - 它是一个功能齐全的应用程序，展示了：
- **实际生产就绪性**：使用Rust构建，快速、可靠和内存安全
- **无缝Cortex Memory集成**：展示利用内存框架的最佳实践
- **实用的AI工作流程**：从多代理对话到音频捕获和内存提取
- **以用户为中心的设计**：美观的TUI界面，具有直观控制和丰富功能
## 探索 Cortex TARS
准备看到Cortex Memory的实际应用？深入了解Cortex TARS项目：
```bash
cd examples/cortex-mem-tars
cargo build --release
cargo run --release
```
查看[Cortex TARS README](examples/cortex-mem-tars/README.md)获取详细的设置说明、配置指南和使用示例。
**Cortex TARS证明Cortex Memory不仅仅是一个框架 - 它是构建智能、内存感知应用的基础，这些应用能够真正理解和记忆。**
# 🏆 基准测试
Cortex Memory 已在 **LoCoMo10 数据集**（conv-26，152 道问题，涵盖 2023 年 5 月至 10 月共 19 个会话）上进行了严格评测，采用与 OpenViking 官方评测完全相同的 **LLM-as-a-Judge** 方法。结果表明 Cortex Memory 在所有对比系统中表现最优。
## 性能比较
综合得分： Cortex Memory v5 达到 68.42% — 超越所有 OpenViking 和 OpenClaw 配置
### 综合得分
| 系统 | 得分 | 问题数 |
|------|:----:|:------:|
| **Cortex Memory v5（Intent ON）** | **68.42%** | 152 |
| OpenViking + OpenClaw（−memory-core） | 52.08% | 1,540 |
| OpenViking + OpenClaw（+memory-core） | 51.23% | 1,540 |
| OpenClaw + LanceDB（−memory-core） | 44.55% | 1,540 |
| OpenClaw（内置记忆） | 35.65% | 1,540 |
### v5 分类得分详情
| 分类 | 说明 | 得分 |
|:----:|------|:----:|
| Cat 1 | 事实召回 | 37.50%（12/32） |
| Cat 2 | 时序推理 | 62.16%（23/37） |
| Cat 3 | 常识推断 | 76.92%（10/13） |
| Cat 4 | 多跳推理 | **84.29%**（59/70） |
| **合计** | | **68.42%**（104/152） |
### Token 效率
| 系统 | 平均每题 Tokens | 得分 | 每千 Token 得分 |
|------|:--------------:|:----:|:--------------:|
| **Cortex Memory v5** | **~2,900** | **68.42%** | **23.6** |
| OpenViking + OpenClaw（−memory-core） | ~2,769 | 52.08% | 18.8 |
| OpenViking + OpenClaw（+memory-core） | ~1,363 | 51.23% | 37.6 |
| OpenClaw（内置记忆） | ~15,982 | 35.65% | 2.2 |
| OpenClaw + LanceDB（−memory-core） | ~33,490 | 44.55% | 1.3 |
> Cortex Memory 比 OpenClaw+LanceDB **节省 11 倍 Token**，每千 Token 得分比率**高出 18 倍**。
### 核心技术优势
- **意图驱动检索**：将多跳查询路由至实体和关联记忆范围，Cat 4 精度提升 +18.75pp
- **L0/L1/L2 分层架构**：从约 100 Token 的精简摘要出发进行精准检索 — 只为真正需要的上下文付费
- **Rust 实现**：高性能、内存安全的核心，以 Qdrant 向量数据库为后端
### 评测框架
评测脚本位于 `examples/locomo-evaluation`，实现了两阶段流水线：
1. **Ingest** — 按 sample 将对话会话写入 Cortex Memory 独立租户
2. **QA** — 通过语义检索 + LLM 生成回答 152 道问题
3. **Judge** — LLM-as-a-Judge 对每个答案评分（CORRECT / WRONG 二值，与 OpenViking 评测方法相同）
有关运行评测的详细说明，请参阅 [locomo-evaluation README](examples/locomo-evaluation/README.md) 以及完整结果 [`examples/locomo-evaluation/BENCHMARK.md`](examples/locomo-evaluation/BENCHMARK.md)。
# 🖥 入门指南
### 先决条件
- [**Rust**](https://www.rust-lang.org)（版本1.86或更高）
- [**Qdrant**](https://qdrant.tech/)向量数据库（版本1.7+）
- 一个**OpenAI兼容**的LLM API端点（用于内存提取和分析）
- 一个**OpenAI兼容**的嵌入API端点（用于向量搜索）
### 安装
最简单的入门方法是使用CLI和Service二进制文件，可以通过`cargo`安装。
```sh
# 安装CLI用于命令行管理
cargo install --path cortex-mem-cli
# 安装REST API服务用于应用集成
cargo install --path cortex-mem-service
# 安装MCP服务器用于AI助手集成
cargo install --path cortex-mem-mcp
```
### 配置
Cortex Memory应用程序（`cortex-mem-cli`、`cortex-mem-service`、`cortex-mem-mcp`）通过`config.toml`文件进行配置。CLI默认在当前目录中查找此文件，或者您可以使用`-c`或`--config`标志传递路径。
这是一个带有解释的示例`config.toml`：
```toml
# -----------------------------------------------------------------------------
# Qdrant向量数据库配置
# -----------------------------------------------------------------------------
[qdrant]
url = "http://localhost:6334" # 您的Qdrant实例的URL（gRPC端口）
http_url = "http://localhost:6333" # REST API的HTTP URL
collection_name = "cortex-memory" # 集合的基本名称（添加租户后缀）
timeout_secs = 5 # Qdrant操作的超时时间
embedding_dim = 1536 # 嵌入维度（例如，text-embedding-3-small为1536）
# -----------------------------------------------------------------------------
# LLM（大语言模型）配置（用于推理、提取）
# -----------------------------------------------------------------------------
[llm]
api_base_url = "https://api.openai.com/v1" # 您的LLM提供商的基本URL
api_key = "${OPENAI_API_KEY}" # API密钥（支持环境变量）
model_efficient = "gpt-5-mini" # 用于提取和分类的模型
model_reasoning = "o1-preview" # 用于复杂推理的模型（可选）
temperature = 0.7 # LLM响应的采样温度
max_tokens = 8192 # LLM生成的最大令牌数
timeout_secs = 60 # LLM请求的超时时间
# -----------------------------------------------------------------------------
# 嵌入服务配置
# -----------------------------------------------------------------------------
[embedding]
api_base_url = "https://api.openai.com/v1" # 您的嵌入提供商的基本URL
api_key = "${OPENAI_API_KEY}" # API密钥（支持环境变量）
model_name = "text-embedding-3-small" # 要使用的嵌入模型的名称
batch_size = 32 # 在单个批次中嵌入的文本数量
timeout_secs = 30 # 嵌入请求的超时时间
# -----------------------------------------------------------------------------
# Cortex数据目录配置
# -----------------------------------------------------------------------------
[cortex]
data_dir = "./cortex-data" # 用于存储内存文件和会话的目录
```
# 🚀 使用方法
### CLI (`cortex-mem-cli`)
CLI提供了直接与内存系统交互的强大界面，二进制名称为 `cortex-mem`。所有命令都需要`config.toml`文件，可以使用`--config `（短选项 `-c`）指定。`--tenant`标志允许多租户隔离。
#### 添加内存
向会话线程添加新消息，自动存储在内存系统中。
```sh
cortex-mem --config config.toml --tenant acme add --thread thread-123 --role user "用户对Rust编程感兴趣。"
```
- `--thread ` / `-t`：（必需）线程/会话ID。
- `--role ` / `-r`：消息角色（user/assistant/system）。默认："user"
- `content`：消息的文本内容（位置参数）。
#### 搜索内存
在内存存储中执行带有加权L0/L1/L2评分的语义向量搜索。
```sh
cortex-mem --config config.toml --tenant acme search "用户的爱好是什么？" --thread thread-123 --limit 10
```
- `query`：搜索的自然语言查询。
- `--thread `：按线程ID过滤内存。
- `--limit ` / `-n`：最大结果数。默认：10
- `--min-score ` / `-s`：最小相关性分数（0.0-1.0）。默认：0.4
- `--scope `：搜索范围："session"、"user"或"agent"。默认："session"
#### 列出内存
从特定URI路径检索内存列表。
```sh
cortex-mem --config config.toml --tenant acme list --uri "cortex://session" --include-abstracts
```
- `--uri ` / `-u`：要列出的URI路径（例如，"cortex://session"或"cortex://user/preferences"）。默认：`cortex://session`
- `--include-abstracts`：在结果中包含L0摘要。
#### 获取特定内存
按其URI检索特定内存。
```sh
cortex-mem --config config.toml --tenant acme get "cortex://session/thread-123/memory-456.md"
```
- `uri`：内存URI。
- `--abstract-only` / `-a`：显示L0摘要而不是完整内容。
- `--overview` / `-o`：显示L1概览而不是完整内容。
#### 删除内存
按其URI从存储中删除内存。
```sh
cortex-mem --config config.toml --tenant acme delete "cortex://session/thread-123/memory-456.md"
```
#### 会话管理
管理对话会话。
```sh
# 列出所有会话
cortex-mem --config config.toml --tenant acme session list
# 创建新会话
cortex-mem --config config.toml --tenant acme session create thread-456 --title "我的会话"
# 关闭会话（触发记忆提取、层级生成和向量索引）
cortex-mem --config config.toml --tenant acme session close thread-456
```
#### 层级管理和统计
管理层级文件并显示系统统计信息。
```sh
# 显示系统统计信息
cortex-mem --config config.toml --tenant acme stats
# 列出可用租户
cortex-mem --config config.toml tenant list
# 显示L0/L1层级文件覆盖状态
cortex-mem --config config.toml --tenant acme layers status
# 生成缺失的L0/L1层级文件
cortex-mem --config config.toml --tenant acme layers ensure-all
# 重新生成超大 L0 摘要文件（> 2K 字符）
cortex-mem --config config.toml --tenant acme layers regenerate-oversized
```
### REST API (`cortex-mem-service`)
REST API允许您将Cortex Memory集成到任何应用程序中，无论编程语言如何。服务默认在端口8085上运行。
#### 启动服务
```sh
# 使用默认设置启动API服务器（默认端口 8085）
cortex-mem-service --config config.toml --host 127.0.0.1 --port 8085
# 启用详细日志记录
cortex-mem-service --config config.toml -h 127.0.0.1 -p 8085 --verbose
```
#### API端点
**健康检查**
- `GET /health`：服务存活检查
- `GET /health/ready`：就绪检查（Qdrant、LLM连接性）
**文件系统操作**
- `GET /api/v2/filesystem/list?uri=`：列出目录内容。
- `GET /api/v2/filesystem/read/`：读取文件内容。
- `POST /api/v2/filesystem/write`：将内容写入文件。
- `GET /api/v2/filesystem/stats?uri=`：获取目录统计信息。
**会话管理**
- `GET /api/v2/sessions`：列出所有会话。
- `POST /api/v2/sessions`：创建新会话。
- `POST /api/v2/sessions/:thread_id/messages`：向会话添加消息。
- `POST /api/v2/sessions/:thread_id/close`：关闭会话并触发内存提取。
**语义搜索**
- `POST /api/v2/search`：在内存中执行带有加权L0/L1/L2评分的语义搜索。
**自动化**
- `POST /api/v2/automation/extract/:thread_id`：为线程触发内存提取。
- `POST /api/v2/automation/index/:thread_id`：为线程触发向量索引。
- `POST /api/v2/automation/index-all`：索引所有线程。
- `POST /api/v2/automation/sync`：手动触发文件系统与向量存储之间的同步。
**租户管理**
- `GET /api/v2/tenants/tenants`：列出所有可用租户。
- `POST /api/v2/tenants/tenants/switch`：切换活动租户上下文。
- `GET /api/v2/tenants/{id}/stats`：获取每租户存储指标。
#### 示例：创建会话和添加消息
```bash
# 创建新会话
curl -X POST http://localhost:8085/api/v2/sessions \
-H "Content-Type: application/json" \
-d '{
"thread_id": "thread-123",
"title": "支持对话"
}'
# 向会话添加消息
curl -X POST http://localhost:8085/api/v2/sessions/thread-123/messages \
-H "Content-Type: application/json" \
-d '{
"role": "user",
"content": "我刚升级到高级计划。"
}'
```
#### 示例：语义搜索
```bash
curl -X POST http://localhost:8085/api/v2/search \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: acme" \
-d '{
"query": "用户当前的订阅状态是什么？",
"thread": "thread-123",
"scope": "session",
"limit": 5,
"min_score": 0.5
}'
```
#### 示例：触发内存提取
```bash
# 从会话中提取内存（通常在会话关闭时调用）
curl -X POST http://localhost:8085/api/v2/automation/extract/thread-123 \
-H "Content-Type: application/json" \
-d '{ "auto_save": true }'
```
### 模型上下文协议（MCP）服务器（`cortex-mem-mcp`）
Cortex Memory提供了MCP服务器，用于与Claude Desktop、Cursor或GitHub Copilot等AI助手集成。MCP服务器通过stdio传输暴露内存工具。
```sh
# 使用配置运行MCP服务器
cortex-mem-mcp --config config.toml --tenant acme
```
MCP服务器暴露以下工具：
- **store_memory**：存储新事实或对话摘要
- **query_memory**：使用自然语言搜索内存
- **list_memories**：按URI前缀枚举可用内存
- **get_memory**：按URI检索特定内存
- **delete_memory**：按URI删除内存
通过将其添加到助手的配置中来配置AI助手使用MCP服务器：
# 🤝 贡献
我们欢迎所有形式的贡献！通过[GitHub Issues](https://github.com/sopaco/cortex-mem/issues)报告错误或提交功能请求。
### 开发过程
1. Fork这个项目
2. 创建功能分支（`git checkout -b feature/amazing-feature`）
3. 提交您的更改（`git commit -m '添加一些很棒的功能'`）
4. 推送到分支（`git push origin feature/amazing-feature`）
5. 创建Pull Request
# 🪪 许可证
本项目根据**MIT许可证**获得许可。详见[LICENSE](LICENSE)文件。
