Thoth Mem
AI编码代理的持久内存
给你的AI编码代理一个在会话、压缩和上下文重置中生存的大脑。
Thoth-Mem是一个带有可选HTTP REST API的MCP服务器,它将您的代理学习到的内容(架构决策、错误修复、模式、首选项)存储在本地SQLite数据库中,并进行全文搜索。当一个新的会话开始时,代理会从它停止的地方继续。```
Agent Session 1 Agent Session 2
┌─────────────────┐ ┌─────────────────┐
│ discovers auth │──── save ───▶│ recalls auth │
│ uses JWT+refresh │ │ pattern instantly │
│ fixes edge case │──── save ───▶│ avoids same bug │
└─────────────────┘ └─────────────────┘
│ ▲
└──── thoth.db (SQLite) ──────────┘
## 特性
- **13个MCP工具** --始终注册,无需配置配置文件
- **HTTP REST API** 使用OpenAPI 3.0文档和交互式 `/docs` 接口
- **CLI+MCP双模式** --用作服务器或直接从终端使用
- **SQLite+FTS5** 全文搜索(快速,零外部依赖)
- **Git友好同步** --将内存导出为gzip压缩块以进行版本控制
- **JSON导出/导入** --便携式存储器备份和传输
- **项目迁移** --在一个操作中重命名所有实体中的项目
- **MCP服务器说明** --连接代理的内置协议指南
- **观测版本控制** --完整历史记录保存在topic_key更新中
- **会话内容丰富** --会话在重新连接时自动填充丢失的项目/目录
- **标准化重复数据删除** --空白/格式不敏感的重复检测
- **严格的类型分类** --在数据库级别强制执行的观察类型
- **分页检索** --通过offset/max_length以块形式提供大观测值
- **隐私保护** — `` 标签在储存前已被剥离
- **令牌高效搜索** --默认情况下结果紧凑,预览模式可选,3层召回协议
- **通过CLI和HTTP使用管理工具** --导出、导入、同步和迁移可用,而不会使MCP工具界面混乱
## 快速开始```bash
# Run directly (no install needed)
npx thoth-mem@latest
# Or install globally
npm install -g thoth-mem
需要Node.js>=18。
MCP配置
克劳德代码```bash
claude mcp add thoth-mem -- npx -y thoth-mem@latest
### OpenCode
添加 `~/.config/opencode/config.json`:```json
{
"mcp": {
"thoth": {
"type": "stdio",
"command": "npx",
"args": ["-y", "thoth-mem@latest"]
}
}
}
Gemini CLI
添加 ~/.gemini/settings.json:```json
{
"mcpServers": {
"thoth": {
"command": "npx",
"args": ["-y", "thoth-mem@latest"]
}
}
}
## CLI命令
Thoth Mem也可以作为一个独立的CLI。当没有给出子命令时,它会启动MCP服务器(默认情况下是HTTP网桥)。```bash
thoth-mem # Start MCP server + HTTP bridge (default)
thoth-mem mcp # Start MCP server (explicit)
thoth-mem search # Search memories
thoth-mem save <content> # Save a memory
thoth-mem timeline <observation_id> # Chronological context around an observation
thoth-mem context # Recent session context
thoth-mem stats # Memory statistics
thoth-mem export [file] # Export to JSON (stdout if no file)
thoth-mem import <file> # Import from JSON
thoth-mem sync [--sync-dir=<path>] # Git sync export
thoth-mem sync-import [--sync-dir=<path>] # Git sync import from another instance
thoth-mem migrate-project <old> <new> # Rename a project across all entities
thoth-mem delete-project <project> # Delete a project and its related data
thoth-mem version # Show version
thoth-mem help # Show help
全局标志适用于任何命令:```bash
thoth-mem stats --data-dir=/custom/path
thoth-mem search "auth pattern" -p my-project
thoth-mem --no-http # Disable HTTP bridge
## HTTP REST API
默认情况下,Thoth-Mem在MCP服务器旁边运行HTTP REST API桥。这座桥在港口监听 `7438` 并通过标准HTTP提供对存储器操作的完全访问。
**交互式文档:**
- OpenAPI规范: `http://localhost:7438/openapi.json`
- 交互式文档: `http://localhost:7438/docs`
**禁用HTTP网桥:**```bash
thoth-mem --no-http
# or
THOTH_HTTP_DISABLED=true thoth-mem
示例:通过HTTP搜索记忆```bash
curl http://localhost:7438/search?query=auth+pattern
**示例:获取内存统计信息**```bash
curl http://localhost:7438/stats
HTTP API支持所有内存操作:会话、观察、提示、搜索、导出/导入和同步。查看互动 /docs API完整引用的接口。
MCP工具(13)
| 工具 | 目的 |
|---|---|
mem_save |
保存结构化观察结果(决策、错误、模式、配置) |
mem_search |
具有压缩/预览模式和精确topic_key查找的全文搜索 |
mem_context |
获取最近的上下文——会话、提示、观察结果、统计数据 |
mem_get_observation |
通过支持分页的ID检索完整观察结果 |
mem_session_start |
注册新的编码会话(幂等) |
mem_session_summary |
在一次通话中保存会话摘要并关闭会话 |
mem_suggest_topic_key |
为追加销售工作流建议一个稳定的topic_key |
mem_capture_passive |
从以下内容中汲取经验教训## Key Learnings: 章节 |
mem_save_prompt |
保存用户提示以备将来调用 |
mem_update |
更新现有观察结果(保留版本历史记录) |
mem_delete |
删除观察(默认为软,硬可选) |
mem_stats |
内存统计数据——会话、观察、提示、项目 |
mem_timeline |
围绕特定观察的时间背景 |
> 管理操作 (导出、导入、同步、迁移项目)可通过 命令行界面 和 HTTP REST API --它们没有注册为MCP工具,以保持代理的工具表面清洁。
同步和可移植性
JSON导出/导入
单个JSON文件中的全内存备份:```bash
Export everything
thoth-mem export backup.json
Export one project
thoth-mem export --project=my-app backup.json
Import (duplicates are skipped via sync_id)
thoth-mem import backup.json
### Git同步
增量,仅追加专为版本控制设计的gzip压缩块——无合并冲突:```bash
# Export a chunk to the sync directory
thoth-mem sync --sync-dir=.thoth-sync
# Structure created:
# .thoth-sync/
# manifest.json ← ordered chunk list
# chunks/
# <timestamp>.json.gz ← compressed memory chunk
在另一台机器上导入:```bash
thoth-mem sync-import --sync-dir=.thoth-sync
每个观察和提示都带有 `sync_id` (UUID),防止重新导入时出现重复。
**增量出口:** 仅导出自上次同步以来的更改,通过变异日志进行跟踪以提高效率。
**墓碑:** 删除的观察结果在同步实例之间正确传播,确保一致性。
**重播安全:** 重新导入相同的数据是安全的;通过以下方式自动检测并跳过重复项 `sync_id`.
### 项目迁移
在一个事务中跨每个实体重命名项目:```bash
thoth-mem migrate-project old-name new-name
以原子方式更新会话、观察和提示。
项目删除
安全删除项目及其相关数据:bash
thoth-mem delete-project project-name
这作为事务运行,如果在另一个项目中检测到共享会话或数据,则阻止删除,并保持同步墓碑的一致性。
配置
| 环境变量 | 默认值 | 描述 |
|---|---|---|
THOTH_DATA_DIR |
~/.thoth |
SQLite数据库的数据目录 |
THOTH_MAX_CONTENT_LENGTH |
100000 |
最大内容长度(警告,从不截断) |
THOTH_MAX_CONTEXT_RESULTS |
20 |
上下文响应中的最大观察值 |
THOTH_MAX_SEARCH_RESULTS |
20 |
返回的最大搜索结果数 |
THOTH_DEDUPE_WINDOW_MINUTES |
15 |
滚动重复数据删除窗口 |
THOTH_PREVIEW_LENGTH |
300 |
搜索结果预览长度 |
THOTH_HTTP_PORT |
7438 |
HTTP REST API端口 |
THOTH_HTTP_DISABLED |
false |
禁用HTTP REST API桥 |
存储
所有数据都存储在一个SQLite数据库中 ~/.thoth/thoth.db (可通过以下方式配置 THOTH_DATA_DIR 或 --data-dir).
- WAL日志模式 用于并发读取性能
- FTS5 对观察结果和提示进行全文搜索
- 外键+检查约束 数据完整性
- 自动架构迁移 实现无缝升级
观察类型
观察结果按照强制分类法进行分类:
| 类型 | 用途 |
|---|---|
decision |
架构或设计选择 |
architecture |
系统结构和模式 |
bugfix |
Bug修复和根本原因 |
pattern |
既定惯例 |
config |
配置和环境设置 |
discovery |
关于代码库的不明显发现 |
learning |
一般学习和陷阱 |
session_summary |
会议结束总结 |
manual |
任何不适合上面的东西 |
许可证
麻省理工学院
