内容
# cory-mem
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/anthropics/mcp)
[](https://fastapi.tiangolo.com/)
为基于Claude的AI项目提供全面的内存系统，实现跨会话的学习、自我组织和持久上下文。
## 概述
cory-mem为AI助手提供个人内存层，允许它们记住上下文，从交互中学习，并跨会话维护持久知识。它将短期会话内存与长期语义存储相结合，通过混合搜索实现自然上下文检索。
## 功能
- **短期（会话）内存**：捕获对话上下文，自动提升到长期存储
- **长期（持久）内存**：具有版本历史和冲突检测的持久存储
- **与FAISS + 关键词搜索的语义搜索**：结合向量相似性和TF-IDF的混合检索
- **可插拔的嵌入提供程序**：支持本地（sentence-transformers）、OpenAI、Claude和Ollama
- **MCP服务器集成**：适用于Claude Code和MCP兼容客户端的原生支持
- **带有FastAPI的REST API**：完整的CRUD操作、搜索端点和分析
- **冲突检测和解决**：自动检测重复、矛盾和合并候选
- **版本历史和备份**：完整的审计轨迹，支持按时间点恢复
- **自动维护调度**：用于同步、修剪和索引优化的后台作业
## 架构
```
+----------------------------------------------------------+
| 客户端层 |
+----------------------------------------------------------+
| 原生Python | MCP服务器 | REST API |
| 库 | (Claude Code) | (FastAPI) |
+-----------------+-----------------+----------------------+
|
+----------------------------------------------------------+
| 核心服务 |
+----------------------------------------------------------+
| 内存管理器 | 搜索引擎 | 调度器 | 冲突 |
| | (混合) | | 解析器 |
+-----------------+---------------+-----------+------------+
|
+----------------------------------------------------------+
| 存储层 |
+----------------------------------------------------------+
| JSON存储 | FAISS索引 | 版本历史 |
| (长期) | (向量) | (审计轨迹) |
+-----------------+---------------+------------------------+
```
### 组件图
```mermaid
graph TB
subgraph "客户端接口"
A[Python库]
B[MCP服务器]
C[REST API]
end
subgraph "核心服务"
D[内存管理器]
E[搜索引擎]
F[调度器]
G[冲突解析器]
H[生命周期跟踪器]
end
subgraph "嵌入提供程序"
I[本地<br/>sentence-transformers]
J[OpenAI]
K[Claude]
L[Ollama]
end
subgraph "存储"
M[(JSON文件)]
N[(FAISS索引)]
O[(版本历史)]
end
A --> D
B --> D
C --> D
D --> E
D --> F
D --> G
D --> H
E --> I
E --> J
E --> K
E --> L
E --> N
D --> M
D --> O
```
## 安装
### 使用uv（推荐）
```bash
# 克隆仓库
git clone https://github.com/yourusername/cory-mem.git
cd cory-mem
# 使用uv安装
uv pip install -e .
# 安装开发依赖项
uv pip install -e ".[dev]"
```
### 使用pip
```bash
pip install -e .
```
### 依赖项
核心依赖项：
- `pydantic>=2.0` - 数据验证
- `fastapi>=0.109` - REST API
- `faiss-cpu` - 向量相似性搜索
- `sentence-transformers` - 本地嵌入
- `mcp` - 模型上下文协议
- `apscheduler>=3.10` - 后台调度
## 快速入门
### 使用MCP服务器与Claude Code
将以下内容添加到您的Claude Code MCP设置（`~/.claude/mcp.json`）：
```json
{
"mcpServers": {
"cory-mem": {
"command": "python",
"args": ["-m", "cory_mem.mcp"],
"env": {
"CORY_MEM_EMBEDDING_PROVIDER": "local"
}
}
}
}
```
然后在Claude Code中，您可以使用内存工具：
```
# 存储内存
Use memory_inject to save: "用户更喜欢Python作为后端开发语言"
# 检索相关上下文
Use memory_retrieve with query: "用户更喜欢什么编程语言？"
```
### 使用REST API
启动API服务器：
```bash
python -m cory_mem.api.main
```
或使用uvicorn：
```bash
uvicorn cory_mem.api.main:app --host 127.0.0.1 --port 8420
```
API端点：
```bash
# 创建内存
curl -X POST http://localhost:8420/api/v1/memories \
-H "Content-Type: application/json" \
-d '{
"content": "用户在Anthropic担任工程师",
"memory_type": "personal",
"tags": ["employment", "career"]
}'
# 搜索内存
curl -X POST http://localhost:8420/api/v1/search \
-H "Content-Type: application/json" \
-d '{
"query": "用户在哪里工作？",
"limit": 5
}'
# 健康检查
curl http://localhost:8420/health
```
### 直接使用Python库
```python
from cory_mem.core.memory_manager import MemoryManager, MemoryContext
from cory_mem.models.base import MemoryType
from cory_mem.config import get_config
# 初始化
config = get_config()
manager = MemoryManager(config)
# 启动会话
session = manager.start_session()
# 添加到短期内存
manager.add_to_session(
session.session_id,
content="用户询问了Python异步模式",
category="interaction"
)
# 注入到长期内存
memory = manager.inject(
content="用户是经验丰富的Python开发者，专门从事异步编程",
memory_type=MemoryType.PERSONAL,
context=MemoryContext(
source="conversation",
tags=["python", "skills", "async"],
confidence=0.9
)
)
# 搜索内存
results = manager.search(
query="用户的编程技能是什么？",
memory_types=[MemoryType.PERSONAL, MemoryType.KNOWLEDGE],
limit=10
)
# 获取对话上下文
context = manager.get_context_for_conversation(
query="帮助我使用异步Python",
session_id=session.session_id,
max_memories=10
)
print(context.to_text())
# 同步会话到长期存储
sync_result = manager.sync_session_to_long_term(session.session_id)
# 获取统计信息
stats = manager.get_stats()
```
## 内存类型
### 个人记忆
存储用户信息：偏好、关系、就业历史。
```python
from cory_mem.models.personal import PersonalMemory, PersonalCategory
memory = PersonalMemory(
content="用户更喜欢深色模式和vim键绑定",
category=PersonalCategory.PREFERENCE,
)
```
类别：
- `PREFERENCE` - 用户偏好和设置
- `EMPLOYMENT` - 工作历史和工作信息
- `RELATIONSHIP` - 家庭、朋友、同事
- `BACKGROUND` - 教育、家乡、生物学
- `GENERAL` - 其他个人信息
### 知识库
事实、技能和特定领域的知识。
```python
from cory_mem.models.knowledge import KnowledgeMemory, KnowledgeDomain
memory = KnowledgeMemory(
content="FAISS使用产品量化进行高效相似性搜索",
domain=KnowledgeDomain.TECHNOLOGY,
knowledge_type="fact"
)
```
领域：
- `TECHNOLOGY`, `SCIENCE`, `BUSINESS`, `ARTS`, `HEALTH`, `EDUCATION`, `GENERAL`
### 交互
对话摘要和交互模式。
```python
from cory_mem.models.interaction import InteractionMemory, InteractionOutcome
memory = InteractionMemory(
content="帮助用户调试异步代码中的竞争条件",
outcome=InteractionOutcome.SUCCESSFUL,
sentiment="positive"
)
```
### 项目
目标、里程碑和进度跟踪。
```python
from cory_mem.models.project import ProjectMemory, ProjectStatus, Milestone
memory = ProjectMemory(
content="为AI构建个人内存系统",
status=ProjectStatus.IN_PROGRESS,
milestones=[
Milestone(name="设计架构", status="completed"),
Milestone(name="实现存储层", status="completed"),
Milestone(name="添加MCP集成", status="in_progress"),
]
)
```
## 配置
通过环境变量（前缀：`CORY_MEM_`）进行配置：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CORY_MEM_MEMORY_BASE_PATH` | `~/.cory-mem/memory` | 存储基准目录 |
| `CORY_MEM_EMBEDDING_PROVIDER` | `local` | 嵌入提供程序：`local`, `openai`, `claude`, `ollama` |
| `CORY_MEM_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | 嵌入模型名称 |
| `CORY_MEM_EMBEDDING_DIMENSION` | `384` | 向量维度大小 |
| `CORY_MEM_OPENAI_API_KEY` | - | OpenAI API密钥（如果使用OpenAI提供程序） |
| `CORY_MEM_ANTHROPIC_API_KEY` | - | Anthropic API密钥（如果使用Claude提供程序） |
| `CORY_MEM_OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama服务器URL |
| `CORY_MEM_SESSION_TTL_HOURS` | `24` | 会话过期时间 |
| `CORY_MEM_MAX_SESSION_ENTRIES` | `1000` | 每个会话的最大条目数 |
| `CORY_MEM_SEARCH_DEFAULT_LIMIT` | `10` | 默认搜索结果数 |
| `CORY_MEM_SEARCH_SIMILARITY_THRESHOLD` | `0.5` | 最小相似性得分 |
| `CORY_MEM_SYNC_INTERVAL_MINUTES` | `60` | 同步作业间隔 |
| `CORY_MEM_PRUNE_INTERVAL_HOURS` | `24` | 清理作业间隔 |
| `CORY_MEM_MAINTENANCE_DAY` | `sunday` | 每周维护日 |
| `CORY_MEM_API_HOST` | `127.0.0.1` | API服务器主机 |
| `CORY_MEM_API_PORT` | `8420` | API服务器端口 |
或使用`.env`文件：
```env
CORY_MEM_EMBEDDING_PROVIDER=openai
CORY_MEM_OPENAI_API_KEY=sk-...
CORY_MEM_API_PORT=9000
```
## API参考
### 内存API（`/api/v1/memories`）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `POST` | `/memories` | 创建新的内存 |
| `GET` | `/memories/{id}` | 通过ID获取内存 |
| `PUT` | `/memories/{id}` | 更新内存 |
| `DELETE` | `/memories/{id}` | 删除内存 |
| `GET` | `/memories` | 列出内存并过滤 |
### 搜索API（`/api/v1/search`）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `POST` | `/search` | 混合搜索（语义+关键词） |
| `POST` | `/search/semantic` | 仅语义搜索 |
| `POST` | `/search/keyword` | 仅关键词搜索 |
| `POST` | `/search/tags` | 按标签搜索 |
### 调度器API（`/api/v1/scheduler`）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/scheduler/jobs` | 列出已计划的作业 |
| `POST` | `/scheduler/jobs/{type}/run` | 手动触发作业 |
| `GET` | `/scheduler/history` | 获取作业执行历史 |
### 版本控制API（`/api/v1/versioning`）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/versioning/{id}/history` | 获取版本历史 |
| `POST` | `/versioning/{id}/restore/{version}` | 恢复到版本 |
| `POST` | `/versioning/backup` | 创建备份 |
### 分析API（`/api/v1/analytics`）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/analytics/stats` | 获取内存统计信息 |
| `GET` | `/analytics/lifecycle` | 获取生命周期指标 |
交互式文档可在`/docs`（Swagger UI）和`/redoc`处访问。
## MCP工具
使用MCP服务器时可用的工具：
| 工具 | 描述 |
|------|-------------|
| `memory_inject` | 将新信息添加到长期内存 |
| `memory_retrieve` | 为查询获取相关上下文 |
| `memory_update` | 修改现有内存 |
| `memory_search` | 使用完整选项进行搜索（语义+关键词） |
| `memory_delete` | 删除内存（软或硬删除） |
### MCP资源
| 资源URI | 描述 |
|--------------|-------------|
| `memory://stats` | 内存系统统计信息 |
| `memory://recent` | 最近访问的内存 |
| `memory://type/{type}` | 按类型分类的内存 |
### MCP提示
| 提示 | 描述 |
|--------|-------------|
| `memory-context` | 为主题获取相关内存上下文 |
| `memory-summary` | 获取存储内存的摘要 |
## 内部操作
### 内存生命周期
```mermaid
sequenceDiagram
participant C as Client
participant M as MemoryManager
participant S as SearchEngine
participant ST as Storage
participant I as FAISS Index
C->>M: inject(content, type)
M->>M: Validate & create Memory
M->>ST: Store JSON
M->>S: Generate embedding
S->>I: Add to index
M-->>C: Return memory
C->>M: search(query)
M->>S: hybrid_search(query)
S->>S: Generate query embedding
S->>I: Vector similarity search
S->>S: Keyword TF-IDF search
S->>S: Merge & rank results
S->>M: Return results
M->>C: Return memories
```
### 冲突解决流程
```mermaid
flowchart TD
A[New Memory] --> B{Compute Similarity}
B --> C{Similarity >= 0.95?}
C -->|Yes| D[DUPLICATE]
C -->|No| E{Similarity >= 0.85?}
E -->|Yes| F[CONTRADICTION]
F -->|Yes| G[Manual Review]
F -->|No| H{Time Diff > 24h?}
H -->|Yes| I[OUTDATED]
H -->|No| J{Similarity >= 0.75?}
E -->|No| J
J -->|Yes| K[MERGE_CANDIDATE]
J -->|No| L[No Conflict]
D --> M{Confidence >= 0.8?}
I --> M
G --> N[Manual Review]
K --> O{Confidence >= 0.9?}
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: Merge]
O -->|No| N
M -->|Yes| P[Auto: Keep Newer]
M -->|No| N
O -->|Yes| Q[Auto: [Auto: Merge]
O -->|No| N
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器