内容
# 记忆轨迹 trailmem
[](https://pypi.org/project/trailmem/)
[](https://pypi.org/project/trailmem/)
[](LICENSE)
**适用于 AI 编程代理的持久化本地图谱记忆。**
Trailmem 为代理提供跨会话的持久化记忆，无供应商锁定：本地 SQLite 知识图谱、类型化关系、显式知识演化、以及基于令牌的简报。它设计用于多个本地代理（如 Claude、Kiro、Codex、OpenCode、Kilo 和 Gemini）共享有用的项目知识，而不会默默地创建无用记忆。
## 快速开始
在 Windows、macOS 和 Linux 上使用相同的命令。
### 安装（推荐：`uv` — 无需 Python）
`trailmem` 是一个命令行工具，因此将其安装为一个工具 — 这会将 `trailmem` 放在每个终端的 `PATH` 中。最干净的方法是 [`uv`](https://docs.astral.sh/uv/)，一个独立的二进制文件，不需要预先安装 Python（它会为您获取一个）：
```bash
# 1. 安装 uv（独立 - 不需要 Python）：
curl -LsSf https://astral.sh/uv/install.sh | sh # Linux / macOS
# Windows（PowerShell）：powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 2. 安装 trailmem（uv 为您下载 Python，如果您没有一个）：
uv tool install trailmem
```
已经有 Python 并更喜欢 [`pipx`](https://pipx.pypa.io/)？`pipx install trailmem` 然后 `pipx ensurepath` 也可以正常工作（pipx 需要一个现有的 Python）。
<details>
<summary>普通 <code>pip</code>（仅在虚拟环境或 CI 中）</summary>
```bash
pip install trailmem
```
`pip install` 将 `trailmem` 命令放入当前 Python 的 `bin`/`Scripts` 文件夹中，通常 **不在您的 `PATH` 上** — 全局 `pip install --user` 或系统 Python 会导致您遇到 `zsh: command not found: trailmem`（在 Debian/Ubuntu 上，还会出现 PEP 668 "外部管理" 错误）。除非您在激活的虚拟环境中工作，否则请使用上面的 `uv`/`pipx`。如果您已经运行了 `pip install` 并遇到 `command not found`，请激活您安装到的虚拟环境或将其作为 `python -m trailmem` 运行 — 或直接切换到 `uv tool install trailmem`。
</details>
### 设置和注册
```bash
trailmem setup # 创建 ~/.trailmem/，初始化数据库，下载默认嵌入模型（~130 MB，一次性）
trailmem doctor # 健康检查
# 将 MCP 服务器注册到您的代理主机：
trailmem integrate # 检测已安装的代理主机，在写入任何配置之前询问
```
`trailmem integrate` 自动检测九个主机：**Claude Code、Codex、Kiro、Kilo、OpenCode、Antigravity、Zed、Cursor、Windsurf**。它会显示它找到的内容，询问一次（y/N），备份它触摸的每个配置（`.bak-trailmem`），跳过已经注册的主机，并且永远不会重写它无法无损解析的配置（JSONC 中的注释会打印手动输入）。在 Claude Code 上，它还会安装一个 `/tm-save` 斜杠命令。
### 在退出前保存会话
一个忘记记录记忆的代理（或一个硬 `/exit`）可能会丢失会话的上下文 — 主机端会话钩子无法帮助，因为它在代理消失后运行，并且永远不会看到会话。只有实时代理在会话中才能捕获。trailmem 为它提供了一个便携式触发器和提醒。
**触发保存** — 使用您的客户端支持的方法（它们都以相同的指令结束：提取此会话的决策/经验教训/任务并调用 `trailmem_store`）：
| 方式 | 适用 | 调用 |
|-----|--------|--------|
| **MCP 提示** `save_session`（零配置，便携） | 任何支持 MCP 提示的客户端 | Claude Code `/mcp__trailmem__save_session` · VS Code `/mcp.trailmem.save_session` · Cursor & Windsurf：斜杠/提示列表 · Zed：仅文本线程 |
| **`/tm-save`** 命令（由 `integrate` 安装） | Claude Code | `/tm-save` |
| **纯文本**（始终有效） | 每个客户端 — `trailmem_store` 工具是通用的 | 输入 *"将此会话保存到 trailmem"* |
不支持客户端（如 **Codex**、**aider**）使用纯文本路径 — 没有任何损失，该工具始终可用。如果您的代理支持 **自定义斜杠命令**，您可以将一个指向同一个指令的命令；格式因主机而异，请查看该主机的命令文件文档（并避免下面的配置雷区）。
**提醒** 以便您记住触发它：
- **状态行** — `trailmem statusline` 打印 `🧠 trailmem: N saved this session`，或者 `⚠ 0 saved · save before exit` 当尚未捕获任何内容时。从 stdin JSON 读取 `session_id`（Claude Code）或 `CLAUDE_CODE_SESSION_ID`/`KIRO_SESSION_ID` 环境变量；只读，始终退出 0。将它集成到您的主机状态行中，或单独运行它。
- **欢迎提示** — 简报以保存提醒结束（由支持会话开始输出的主机显示，例如 Codex、Kilo）。
- **下一会话标志** — 如果前一个会话未存储任何内容，则下一个欢迎消息会带有响亮的提醒。
> **您正在连接一个未列出的代理？** MCP 配置格式不统一，错误的猜测可能会破坏代理的启动。已知的雷区：**VS Code / Copilot** 使用 `servers` 键（不是 `mcpServers`）；**Continue** 和 **Goose** 使用 YAML（JSON 编写器会损坏它们）；**aider** 根本不支持 MCP。始终遵循代理自己的当前文档。所有这些都不需要的是上面的纯文本路径。
如果您更喜欢手动 MCP 注册？每个主机都有自己的机制：
| 主机 | 手动注册 |
|------|--------------------|
| Claude Code | `claude mcp add trailmem -- trailmem-mcp` |
| Codex | 在 `~/.codex/config.toml` 中添加 `[mcp_servers.trailmem]` 表 |
| Kiro | 在 `~/.kiro/settings/mcp.json` 中的 `mcpServers` 下添加 `trailmem` |
| Kilo | 在 `~/.config/kilo/kilo.jsonc` 中的 `mcp` 下添加 `trailmem`，格式为 `{"type":"local","command":["trailmem-mcp"]}`（kilo 7.x 格式） |
| OpenCode | 在 `~/.config/opencode/opencode.json` 中的 `mcp` 下添加 `trailmem` |
| Antigravity | 在 `~/.gemini/config/mcp_config.json` 中的 `mcpServers` 下添加 `trailmem` |
| Zed | 在 `~/.config/zed/settings.json` 中的 `context_servers` 下添加 `trailmem` |
| Cursor | 在 `~/.cursor/mcp.json` 中的 `mcpServers` 下添加 `trailmem` |
| Windsurf | 在 `~/.codeium/windsurf/mcp_config.json` 中的 `mcpServers` 下添加 `trailmem` |
### 任何其他 MCP 代理
Trailmem 与 **任何支持 MCP 的代理** 配合使用 — Cursor、Windsurf、Cline、Zed、Gemini CLI 或其他更新的代理。`trailmem integrate` 仅自动执行上述主机；对于其他所有主机，请您自己注册。您只需要三个事实：
1. **传输：** stdio（无 URL，无端口，无 HTTP）。
2. **命令：** `trailmem-mcp` — 无参数，无环境变量要求。
3. **服务器名称：** `trailmem`（任何名称都有效；工具名称不依赖于它）。
大多数代理使用以下格式的 JSON 块：
```json
{
"mcpServers": {
"trailmem": {
"command": "trailmem-mcp",
"args": []
}
}
}
```
如果代理找不到命令，请使用绝对路径 — 使用以下方法打印：
```bash
which trailmem-mcp # Windows: where trailmem-mcp
```
然后重启代理并检查连接：代理应该看到六个 `trailmem_*` 工具，并且调用 `trailmem_welcome` 应该返回一个简报。`trailmem doctor` 验证数据库端。
### 更新
```bash
uv tool upgrade trailmem # 如果使用 uv 安装
pipx upgrade trailmem # 如果使用 pipx 安装
pip install --upgrade trailmem # 如果使用 pip 安装（在虚拟环境中）
```
没有应用内 "更新可用" 通知 — trailmem 按设计不发送任何遥测数据。请改为查看 GitHub 版本发布页面。
代理然后获得六个工具：`trailmem_welcome`（每个会话一次简报）、`trailmem_store`、`trailmem_query`、`trailmem_show`、`trailmem_edit`、`trailmem_link`。所有这些也可以通过 `trailmem` CLI 提供给人类（`store`、`query`、`show`、`list`、`stats`、`link`、`archive` 等）。
从 CLI 试用它（注意：`content` 是位置参数；`--agent user` 用于您自己的笔记）：
```bash
trailmem store --title "第一个笔记" --type lesson --agent user "值得记住的事情。"
trailmem query "我之前记下了什么"
trailmem list
trailmem help # 或：trailmem <command> --help
```
## 为什么
- **本地优先。** 一个 SQLite 文件（`~/.trailmem/trailmem.db`），WAL 模式，无云，无守护进程。嵌入式模型通过 ONNX 运行（默认：bge-small-en-v1.5，用户可使用 `trailmem model use` 交换）。
- **图谱，而非列表。** 类型化边（`related`、`supersedes`、`evolves`、`contradicts`、`derived_from`），存储时的孤儿警告，取代链而不是破坏性覆盖。
- **令牌纪律。** 上下文仅在每个会话中注入一次（欢迎，~600–800 个令牌）。绝不进行逐回合注入。重复欢迎返回简短形式。
- **无垃圾记忆。** 4 波段重复检测（精确哈希拒绝 → >0.92 阻止 → 0.85–0.92 警告 → 接受），强制标题，无归属存储硬拒绝，无自动存储生命周期钩子。
- **无遥测。** 服务器仅写入用户需要的内容（例如本地 `hooks.log` 诊断）；它绝不发出分析数据 — 一个刻意的反目标，而不是疏忽。
## 状态
v0.1.0 [已在 PyPI 上线](https://pypi.org/project/trailmem/)。核心功能已实现并测试：模式、存储/去重、查询/显示、欢迎、MCP 服务器、CLI、钩子、模型管理、循环仪表盘、主机集成。设计合约位于 [`docs/`](docs/index.md) — 模式、欢迎生命周期、重复策略、演化规则、CLI/MCP 接口、钩子、播种剧本和仪表盘合约。
## 许可证
MIT
