Thoth Mem

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工具界面混乱

快速开始

# Run directly (no install needed)
npx thoth-mem@latest

# Or install globally
npm install -g thoth-mem

需要Node.js>=18。

MCP配置

克劳德代码

claude mcp add thoth-mem -- npx -y thoth-mem@latest

OpenCode

添加 ~/.config/opencode/config.json:

{
  "mcp": {
    "thoth": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "thoth-mem@latest"]
    }
  }
}

Gemini CLI

添加 ~/.gemini/settings.json:

{
  "mcpServers": {
    "thoth": {
      "command": "npx",
      "args": ["-y", "thoth-mem@latest"]
    }
  }
}

CLI命令

Thoth Mem也可以作为一个独立的CLI。当没有给出子命令时，它会启动MCP服务器（默认情况下是HTTP网桥）。

thoth-mem                              # Start MCP server + HTTP bridge (default)
thoth-mem mcp                          # Start MCP server (explicit)
thoth-mem search                # Search memories
thoth-mem save         # Save a memory
thoth-mem timeline     # 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                 # Import from JSON
thoth-mem sync [--sync-dir=
]     # Git sync export
thoth-mem sync-import [--sync-dir=
]  # Git sync import from another instance
thoth-mem migrate-project 
   # Rename a project across all entities
thoth-mem delete-project 
     # Delete a project and its related data
thoth-mem version                      # Show version
thoth-mem help                         # Show help

全局标志适用于任何命令：

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网桥：

thoth-mem --no-http
# or
THOTH_HTTP_DISABLED=true thoth-mem

示例：通过HTTP搜索记忆

curl http://localhost:7438/search?query=auth+pattern

示例：获取内存统计信息

curl http://localhost:7438/stats

HTTP API支持所有内存操作：会话、观察、提示、搜索、导出/导入和同步。查看互动 /docs API完整引用的接口。

MCP工具（13）

管理操作 （导出、导入、同步、迁移项目）可通过 命令行界面 和 HTTP REST API --它们没有注册为MCP工具，以保持代理的工具表面清洁。

同步和可移植性

JSON导出/导入

单个JSON文件中的全内存备份：

# 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压缩块——无合并冲突：

# Export a chunk to the sync directory
thoth-mem sync --sync-dir=.thoth-sync

# Structure created:
# .thoth-sync/
#   manifest.json        ← ordered chunk list
#   chunks/
#     .json.gz ← compressed memory chunk

在另一台机器上导入：

thoth-mem sync-import --sync-dir=.thoth-sync

每个观察和提示都带有 sync_id （UUID），防止重新导入时出现重复。

增量出口： 仅导出自上次同步以来的更改，通过变异日志进行跟踪以提高效率。

墓碑： 删除的观察结果在同步实例之间正确传播，确保一致性。

重播安全： 重新导入相同的数据是安全的；通过以下方式自动检测并跳过重复项 sync_id.

项目迁移

在一个事务中跨每个实体重命名项目：

thoth-mem migrate-project old-name new-name

以原子方式更新会话、观察和提示。

项目删除

安全删除项目及其相关数据：

thoth-mem delete-project project-name

这作为事务运行，如果在另一个项目中检测到共享会话或数据，则阻止删除，并保持同步墓碑的一致性。

配置

存储

所有数据都存储在一个SQLite数据库中 ~/.thoth/thoth.db （可通过以下方式配置 THOTH_DATA_DIR 或 --data-dir).

• WAL日志模式 用于并发读取性能
• FTS5 对观察结果和提示进行全文搜索
• 外键+检查约束 数据完整性
• 自动架构迁移 实现无缝升级

观察类型

观察结果按照强制分类法进行分类：

许可证

麻省理工学院