内容
# aimemo
[](https://golang.org/) [](LICENSE) [](https://github.com/MyAgentHubs/aimemo/releases)
[English](README.md) | [中文](README.zh-CN.md)
适用于 AI 智能体的无依赖 MCP 内存服务器 - 持久化、可搜索、本地优先、单二进制文件。
```
$ claude "let's keep working on the payment service"
╭─ memory_context ──────────────────────────────────────────────────╮
│ [project: payment-service] │
│ │
│ Last session (3 days ago): │
│ • Stripe webhook signature verification — DONE │
│ • Idempotency key refactor — IN PROGRESS │
│ • Blocked: race condition in concurrent refund handler │
│ │
│ Related: Redis connection pool, pkg/payments/refund.go │
╰───────────────────────────────────────────────────────────────────╯
Picking up where we left off. The race condition in the refund
handler looks like a missing mutex around the in-flight map.
Let me check pkg/payments/refund.go ...
[... Claude works through the fix ...]
╭─ memory_store (journal) ──────────────────────────────────────────╮
│ Resolved refund race — added sync.Mutex around inFlightRefunds. │
│ Tests passing. Next: load test with k6 at 500 rps. │
╰───────────────────────────────────────────────────────────────────╯
```
## 🧠 为什么选择 aimemo
- **无需复杂的环境配置**。单 Go 二进制文件。无需 Docker、无需 Node.js 运行时、无需云账户、无需 API 密钥。`brew install` 仅需 30 秒。
- **内存与项目绑定**。存储在 `.aimemo/` 目录下，与代码放在一起 - 可提交到 git 或添加到 `.gitignore`。切换分支；内存随目录。
- **Claude 自动衔接**。`memory_context` 在每次会话开始时自动触发。Claude 看到它之前在做什么、什么被阻塞了、做出了什么决定。你不再需要重复自己。
- **全文搜索，正确排序**。FTS5 + BM25 评分按最近性和访问频率加权。相关记忆优先显示；旧噪音自然消退。
- **并发会话，无损坏**。SQLite WAL 模式允许多个 Claude 窗口同时写入，无需相互锁定。
- **您始终保持控制**。Claude 使用的每个工具，您都可以在终端中使用。检查、编辑、撤销、导出。您的内存是可读的 Markdown 或 JSON - 永远不会锁定在专有格式中。
## ⚡ 快速开始
```bash
# 1. 安装
# Linux/macOS (一键安装):
curl -sSL https://raw.githubusercontent.com/MyAgentHubs/aimemo/main/install.sh | bash
# 或 macOS via Homebrew:
brew install MyAgentHubs/tap/aimemo
# 2. 为您的项目初始化内存（在项目根目录运行）
aimemo init
# 3. 注册到 Claude Code
claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'
```
重启 Claude Code。在下一次会话中，Claude 将自动加载项目上下文。
### OpenClaw 快速开始
如果您正在使用 OpenClaw 技能，请参阅下面的 [OpenClaw 集成](#-openclaw-integration) 部分以实现每个技能的内存隔离。
## 🔧 工作原理
`aimemo serve` 作为 stdio MCP 服务器运行；Claude Code 管理进程生命周期，因此您无需手动维护。当 Claude 启动会话时，它调用 `memory_context` 加载相关上下文；当它工作时，它调用 `memory_store` 和 `memory_link` 记录决策和关系。您可以在任何时候调用 `aimemo search`、`aimemo list` 或 `aimemo get` 从终端读取或编辑相同的数据。所有数据都存储在 `.aimemo/` 目录下的 SQLite 数据库中，该目录通过从当前目录向上查找发现，就像 Git 查找 `.git/` 目录一样。
## 🛠 MCP 工具
| 工具 | 描述 | Claude 何时调用它 |
|------|-------------|----------------------|
| `memory_context` | 返回当前项目的最新、相关的观察结果 | 会话开始 - 自动 |
| `memory_store` | 保存观察结果（事实、决定、日志条目、待办事项） | 完成任务或做出决定后 |
| `memory_search` | 跨所有观察结果进行全文搜索，BM25 排名 | 需要回忆特定内容时 |
| `memory_forget` | 按 ID 软删除观察结果 | 指示丢弃某些内容时 |
| `memory_link` | 在两个观察结果之间创建命名关系 | 确定依赖关系或连接时 |
所有工具模式总计不到 2,000 个令牌。每个调用都有严格的 5 秒超时 - 服务器不会阻塞您的会话。空状态查询在 5 毫秒内返回。
## 📋 CLI 参考
### 设置
| 命令 | 描述 |
|---------|-------------|
| `aimemo init` | 在当前目录中创建 `.aimemo/` |
| `aimemo serve` | 启动 MCP stdio 服务器（由 Claude Code 自动调用） |
| `aimemo doctor` | 验证数据库健康状况、FTS5 支持、WAL 模式和 MCP 注册 |
### 内存
| 命令 | 描述 |
|---------|-------------|
| `aimemo add <name> <type> [observations...] [--tag]` | 添加具有一个或多个观察结果的实体 |
| `aimemo observe <entity-name> <observation>` | 添加新观察结果到现有实体 |
| `aimemo retract <entity-name> <observation>` | 从实体中删除特定观察结果 |
| `aimemo forget <entity-name> [--permanent]` | 软删除实体（可恢复）；使用 `--permanent` 进行硬删除 |
| `aimemo search <query>` | 全文搜索，返回排序结果 |
| `aimemo get <entity-name>` | 显示具有所有观察结果和关系的实体 |
| `aimemo link <from> <relation> <to>` | 在两个实体之间创建类型化关系 |
| `aimemo append <entity-name> <observation>` | 添加观察结果到实体（别名：`observe`） |
### 日志
| 命令 | 描述 |
|---------|-------------|
| `aimemo journal` | 打开交互式日志条目（尊重 `$EDITOR`） |
| `aimemo journal <text>` | 记录快速的内联日志条目 |
### 检查和导出
| 命令 | 描述 |
|---------|-------------|
| `aimemo list` | 列出最近的观察结果 |
| `aimemo tags` | 列出所有正在使用的标签 |
| `aimemo stats` | 显示数据库大小、观察结果数量、最后写入时间 |
| `aimemo export --format md` | 将所有内存导出为 Markdown |
| `aimemo export --format json` | 将所有内存导出为 JSON |
| `aimemo import <file>` | 从 JSONL 或 JSON 导出文件导入 |
所有命令都接受 `--context <name>` 以针对命名上下文（单独的 `.db` 文件位于 `.aimemo/` 目录中）。
## ⚙️ 配置
`~/.aimemo/config.toml` - 全局默认值，均可选：
```toml
[defaults]
context = "main" # 默认上下文名称
max_results = 20 # `memory_context` 返回的观察结果数量
[scoring]
recency_weight = 0.7 # 0-1，近期权重与访问频率权重
[server]
timeout_ms = 5000 # 每个 MCP 调用超时
log_level = "warn" # "debug" | "info" | "warn" | "error"
```
每个项目的覆盖配置存储在项目根目录的 `.aimemo/config.toml` 中 - 相同的键，项目值优先于全局值。
## 🤖 Claude Code 集成
在每台机器上注册一次服务器：
```bash
claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'
```
将以下内容添加到项目的 `CLAUDE.md` 中，以便 Claude 知道内存可用以及如何使用它：
```markdown
## 内存
该项目使用 aimemo 进行跨会话的持久内存。
- 在每次会话开始时调用 `memory_context` 以加载之前的上下文。
- 在会话结束时调用 `memory_store`，类型为 `journal`，以记录已完成的内容、正在进行的内容和阻塞点。
- 使用 `memory_link` 连接相关观察结果（例如，错误与其修复、决策及其理由）。
- 不要存储秘密、凭证或个人身份信息。
```
## 🦞 OpenClaw 集成
aimemo 通过 **每个技能的内存隔离** 和 **零基础设施** 解决了 OpenClaw 的“记住一切但不理解任何东西”的问题。
### 为什么 aimemo 适用于 OpenClaw？
**问题：**
- OpenClaw 的原生 Markdown 内存随着使用次数增加而效果变差
- 技能共享内存，导致交叉污染
- 上下文压缩丢失重要上下文
**解决方案：**
- ✅ **零依赖** - 单 Go 二进制文件，无 Docker/Node.js/数据库
- ✅ **每个技能隔离** - 每个技能都有自己的内存数据库
- ✅ **实际工作** - BM25 搜索 + 重要性评分查找相关内容
- ✅ **本地优先** - 所有数据保留在您的机器上
**与其他解决方案的比较：**
| | aimemo | Cognee | memsearch | Supermemory |
|---|--------|---------|-----------|-------------|
| **依赖** | 零 | Neo4j/Kuzu | Milvus | 云服务 |
| **安装** | 30 秒 | 复杂 | 复杂 | 需要注册 |
| **技能隔离** | 内置 | 手动 | 手动 | 不适用 |
| **Linux 支持** | ✅ 原生 | ✅ | ✅ | 不适用 |
### 5 分钟设置
```bash
# 1. 安装（Linux amd64/arm64）
curl -sSL https://raw.githubusercontent.com/MyAgentHubs/aimemo/main/install.sh | bash
# 2. 将 MCP 服务器注册到 OpenClaw
claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'
# 或添加到 ~/.openclaw/openclaw.json：
# {
# "mcpServers": {
# "aimemo-memory": {
# "command": "/usr/local/bin/aimemo",
# "args": ["serve"]
# }
# }
# }
# 3. 初始化工作区内存
cd ~/.openclaw/workspace
aimemo init
# 4. 重启 OpenClaw Gateway
# Linux: systemctl --user restart openclaw-gateway
# macOS: launchctl stop com.openclaw.gateway && launchctl start com.openclaw.gateway
```
### 每个技能的内存隔离
每个技能通过使用 `context` 参数获得自己的隔离内存：
**在您的 SKILL.md 中：**
```markdown
---
name: my-skill
description: A skill with persistent memory
---
# 我的技能
## 说明
执行工作时：
1. **首先加载内存**：
```
memory_context({context: "my-skill"})
```
2. 使用加载的上下文执行任务
3. **存储学习成果**：
```
memory_store({
context: "my-skill",
entities: [{
name: "preferences",
entityType: "config",
observations: ["User prefers snake_case"]
}]
})
```
**关键**：始终传递 `context: "my-skill"` 以防止内存污染。
**结果：**
```
~/.openclaw/workspace/.aimemo/
├── memory.db # 共享/默认（无上下文）
├── memory-skill-a.db # 技能 A 的隔离内存
├── memory-skill-b.db # 技能 B 的隔离内存
└── memory-skill-c.db # 技能 C 的隔离内存
```
### 完整示例
参见 [`examples/openclaw-github-pr-reviewer/`](examples/openclaw-github-pr-reviewer/) 以获取一个完整的技能示例，该技能：
- 审查 GitHub PR
- 学习代码样式偏好
- 跨会话记住模式
- 存储反馈以供改进
### 文档
- **[OpenClaw 集成指南](docs/openclaw-integration.md)** - 逐步设置
- **[OpenClaw 工作流程](docs/openclaw-workflow.md)** - 架构深入解析
- **[示例技能](examples/openclaw-github-pr-reviewer/)** - 完整实现
### 调试
```bash
# 列出技能的内存
aimemo list --context my-skill
# 在技能内搜索
aimemo search "keyword" --context my-skill
# 导出以便检查
aimemo export --context my-skill --format json > memory.json
# 获取数据库统计信息
aimemo stats --context my-skill
```
## 🖥 客户端支持
aimemo 与任何 MCP 兼容的 AI 编码客户端配合使用。服务器命令始终为 `aimemo serve`。
> **PATH 注意（macOS/Homebrew）：** GUI 应用程序可能不会继承您的 shell PATH。如果客户端找不到 `aimemo`，请使用绝对路径 `/opt/homebrew/bin/aimemo` 代替。
### Claude Code
```bash
claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'
```
或将 `.mcp.json` 提交到项目根目录（参见此存储库中的示例）。
### Cursor
项目本地（`.cursor/mcp.json`）或全局（`~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"aimemo-memory": {
"command": "aimemo",
"args": ["serve"]
}
}
}
```
### Windsurf
编辑 `~/.codeium/windsurf/mcp_config.json`（仅全局）：
```json
{
"mcpServers": {
"aimemo-memory": {
"command": "aimemo",
"args": ["serve"]
}
}
}
```
### OpenAI Codex CLI
项目本地（`.codex/config.toml`）或全局（`~/.codex/config.toml`）：
```toml
[mcp_servers.aimemo-memory]
command = "aimemo"
args = ["serve"]
```
### Cline（VS Code）
编辑 `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:
```json
{
"mcpServers": {
"aimemo-memory": {
"command": "aimemo",
"args": ["serve"],
"disabled": false,
"alwaysAllow": []
}
}
}
```
### Continue（VS Code / JetBrains）
项目本地（`.continue/mcpServers/aimemo-memory.yaml`）：
```yaml
name: aimemo-memory
version: 0.0.1
schema: v1
mcpServers:
- name: aimemo-memory
command: aimemo
args:
- serve
```
或添加到全局 `~/.continue/config.yaml` 下的 `mcpServers:` 键。
### Zed
在 `~/.zed/settings.json`（全局）或 `.zed/settings.json`（项目本地）：
```json
{
"context_servers": {
"aimemo-memory": {
"source": "custom",
"command": "aimemo",
"args": ["serve"],
"env": {}
}
}
}
```
## 🤝 贡献
错误报告和功能请求请在 [GitHub Issues](https://github.com/MyAgentHubs/aimemo/issues) 中提交。欢迎提交拉取请求 - 对于非琐碎的更改，请先开启一个问题，以便我们在您投入时间编写代码之前达成一致。
