内容
# SimpleMem
一款为 Claude 编写的、充满活力的内存管理系统，具备 RAG 能力，通过模型上下文协议（MCP）实现。
> ⚠️ **警告**：该项目完全是充满活力的编码。它的确能运行，但请不要太过关注实现细节。这些代码是由一个玩得开心的 AI 编写的，而不是遵循最佳实践的人类编写的。
## 什么是 SimpleMem？
SimpleMem 是一个 MCP 服务器，为 Claude 和其他 MCP 客户端提供持久的内存存储和检索功能。它将传统的基于文件的存储与现代的 RAG（检索增强生成）能力相结合，包括语义搜索和自动关系发现。
你可以把它想象成 Claude 的个人笔记本，它永远不会忘记，并且可以自动找到想法之间的联系。
## 功能
- 📝 **持久内存存储**：存储和检索带有丰富元数据的记忆
- 🔍 **语义搜索**：使用自然语言查询查找记忆
- 🔗 **自动关系发现**：语义反向链接连接相关记忆
- 🏷️ **标签系统**：使用灵活的标签组织记忆
- 🎯 **向量嵌入**：由 Voyage AI 提供支持，实现高质量的语义理解
- 📊 **DuckDB 后端**：快速、有效的存储，支持向量相似性搜索
- 🔧 **MCP 协议**：与 Claude 和其他 MCP 客户端无缝集成
## 快速入门
### 前置条件
- Go 1.21+
- Voyage AI API 密钥（参见下面的配置部分）
### 安装
#### 选项 1：下载预编译二进制文件
从 [GitHub Releases](https://github.com/jcdickinson/simplemem/releases) 下载适用于您平台的最新版本：
- **Linux AMD64**：`simplemem-vX.X.X-linux-amd64.tar.gz`
解压并将二进制文件放在您的 PATH 中。
#### 选项 2：从源代码构建
```bash
# 克隆仓库
git clone https://github.com/jcdickinson/simplemem
cd simplemem
# 安装依赖项
just deps
# 构建二进制文件
just build
```
#### 选项 3：Nix
如果您启用了 Nix 和 flakes：
```bash
# 直接从 GitHub 运行
nix run github:jcdickinson/simplemem
# 或克隆并在本地运行
git clone https://github.com/jcdickinson/simplemem
cd simplemem
nix run
# 安装到配置文件
nix profile install github:jcdickinson/simplemem
# 在开发环境中运行
nix develop
```
### 配置
SimpleMem 使用基于 TOML 的配置，提供灵活的 API 密钥和设置选项。
#### 配置文件
创建一个 `config.toml` 文件（参见 `config.toml.example` 作为参考）：
```toml
[voyage_ai]
model = "voyage-3.5"
rerank_model = "rerank-lite-1"
api_key = { "path" = "~/.config/simplemem/voyage_api_key.txt" }
# 或
api_key = "api-key-here"
```
#### 环境变量
您也可以使用环境变量进行配置：
```bash
export SIMPLEMEM_VOYAGE_AI_API_KEY="your-api-key"
export SIMPLEMEM_VOYAGE_AI_MODEL="voyage-3.5"
export SIMPLEMEM_VOYAGE_AI_RERANK_MODEL="rerank-lite-1"
```
#### 配置选项
- **自定义配置文件**：使用 `--config path/to/config.toml`
- **数据库路径**：使用 `--db path/to/database.db`（也可以在配置文件中设置）
- **API 密钥来源**：文件路径（推荐）或直接值
- **多个配置文件**：为不同项目使用不同的配置文件
### 使用
#### 作为 MCP 服务器
在您的 MCP 客户端配置文件中添加：
```json
{
"mcpServers": {
"simplemem": {
"command": "./simplemem",
"args": [
"--db",
"path/to/your/database.db",
"--config",
"path/to/config.toml"
]
}
}
}
```
#### 命令行测试
```bash
# 创建一个记忆
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"create_memory","arguments":{"name":"my-memory","metadata":{"title":"My First Memory","description":"A test memory","tags":{"category":"test","priority":"low"}},"content":"# Hello World\n\nThis is my first memory!"}},"id":1}'
# 搜索记忆（主要发现方法）
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_memories","arguments":{"query":"hello world"}},"id":1}'
# 读取特定记忆
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read_memory","arguments":{"name":"my-memory"}},"id":1}'
```
#### 测试语义反向链接
```bash
# 运行综合语义反向链接测试
just test-backlinks
# 验证反向链接是否正常工作
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_backlinks","arguments":{"name":"my-memory"}},"id":1}'
```
## 可用工具（MCP）
- **`create_memory`**：使用元数据对象和 Markdown 内容创建新记忆
- **`read_memory`**：按名称读取特定记忆
- **`update_memory`**：更新现有记忆的元数据和内容
- **`delete_memory`**：删除记忆和所有相关数据
- **`search_memories`**：语义搜索，支持可选标签过滤（主要发现方法）
- **`get_backlinks`**：获取与特定记忆相关的记忆
- **`change_tag`**：修改记忆上的标签
> **注意**：`list_memories` 已暂时删除，以鼓励使用高效的语义搜索，而不是基于令牌的完整列表。
## 记忆格式
### API 结构（用于 create_memory/update_memory）
```json
{
"name": "my-memory-name",
"metadata": {
"title": "A Human-Readable Title",
"description": "Brief description of the memory",
"tags": {
"category": "personal",
"priority": "high",
"status": "active"
},
"custom_field": "any_value",
"version": "1.0"
},
"content": "# Memory Content\n\nYour memory content in **Markdown** format.\n\n- Clean markdown without frontmatter\n- Links to [[other-memories]]\n- Whatever you need!"
}
```
### 磁盘存储
记忆存储为 YAML 前置元数据 + Markdown：
```markdown
---
title: A Human-Readable Title
description: Brief description of the memory
tags:
category: personal
priority: high
status: active
custom_field: any_value
version: "1.0"
created: 2025-01-24T12:00:00Z
modified: 2025-01-24T12:00:00Z
---
# Memory Content
Your memory content in **Markdown** format.
- Clean markdown without frontmatter
- Links to [[other-memories]]
- Whatever you need!
```
## 开发
### 前置条件
- [Just](https://github.com/casey/just) 命令行运行器
### 常用命令
```bash
# 显示可用命令
just
# 运行测试（当测试存在时）
just test
# 格式化代码
just fmt
# 以详细日志运行
just run-verbose
# 测试语义反向链接功能
just test-backlinks
# 清理构建产物
just clean
```
### 调试测试
用于快速开发迭代：
```bash
# 使用自定义数据库测试任何 JSON-RPC 调用
just test-json '<json>' /tmp/test.db
# 快速最小测试
just test-clean /tmp/debug.db
# 一步构建和测试
just build-test
```
## 架构
- **前端**：MCP JSON-RPC 2.0 协议服务器
- **存储**：基于文件的内存存储，带有 DuckDB 后端
- **搜索**：Voyage AI 嵌入 + 向量相似性
- **关系**：自动语义反向链接发现
- **记忆**：YAML 前置元数据 + Markdown 内容
## 已知问题
- 没有适当的测试套件（它是充满活力的代码，记得吗？）
- 错误处理可能更强大
- 一些边缘情况可能会导致崩溃
- 文档是这个 README 所涵盖的内容
- 数据库迁移？那是什么？
## 贡献
这是一个充满活力的项目，所以贡献应该与氛围相符：
1. 先使其工作
2. 再使其工作得更好
3. 使其变得漂亮……也许以后会？
4. 测试是理想的
5. 如果它损坏了，就用更多的活力修复它
## 许可证
LGPL 3.0 - 使用它，修改它，与它共鸣（但与社区分享改进）。
## 致谢
- 充满爱和咖啡因构建
- 由 [Voyage AI](https://voyageai.com) 嵌入提供支持
- 使用 [DuckDB](https://duckdb.org) 进行存储
- 通过 [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) 实现 MCP 集成
---
_"它在我的机器上运行，而且那台机器有很好的氛围。"_ ✨
