内容
# Pathmark
无需每次切换代理时重新解释你的仓库。
<p align="center">
<img src="assets/pathmark-hero.png" alt="Pathmark 本地内存层，由 Codex、Claude Code、opencode 和 Gemini CLI 共享" width="100%">
</p>
Pathmark 为 Codex、Claude Code、opencode、Gemini CLI、Cursor 和任何支持 MCP 的工具提供了一个本地内存层。一次性保存决策、项目规则、偏好和结论。从下一个代理开始使用，无需粘贴总结。
你的上下文存储在磁盘上的 `~/.pathmark/memory/memory.jsonl`。你不需要账户、托管数据库、API 密钥或供应商后端即可开始。
## 为什么选择 Pathmark
你不会在一个工具中工作。你要求 Codex 进行补丁，Claude Code 进行审查，opencode 进行清理，Gemini CLI 对计划提出质疑。每个工具都从头开始，除非你手动传递上下文。
Pathmark 为这些工具提供了一个共同的内存读写位置：
- 跨代理的一个本地 JSONL 存储。
- 标准 MCP 工具：`remember`、`search_memory`、`get_context` 和 `ask_memory`。
- 默认情况下客户端合成，这样你的编码代理可以读取上下文并回答。
- 可选的 Codex CLI、本地命令和 OpenAI 兼容的合成模式。
- 你可以检查、备份、删除或迁移的纯文件。
Pathmark 保持提供者中立。Codex 获得一个可选的合成预设。核心服务器与任何可以使用本地工具的 MCP 客户端一起工作。
## 跨代理内存
你在编码会话期间切换工具：
- Codex 修复失败的测试。
- Claude Code 审查补丁。
- opencode 清理差异。
- Gemini CLI 挑战该方法。
Pathmark 将笔记保存在一个存储中。
将每个代理指向同一个存储：
```text
Codex \
Claude Code \
opencode > Pathmark MCP > ~/.pathmark/memory/memory.jsonl
Gemini CLI /
Cursor /
```
在每个代理中安装 Pathmark，并将它们指向同一个 `PATHMARK_STORE_DIR`。一个工具使用 `remember` 或 `create_conclusion` 保存上下文；下一个工具使用 `search_memory`、`get_context` 或 `ask_memory` 恢复它。
Pathmark 作为一个内存总线位于代理之下，为你的编码工作流提供支持。
## 工具
Pathmark 提供了这些 MCP 工具：
| 工具 | 用途 |
| --- | --- |
| `remember` | 保存一个原始的内存项。 |
| `create_conclusion` | 保存一个更高信号的持久结论或偏好。 |
| `search_memory` | 搜索内存和结论。 |
| `get_context` | 返回任务或问题的紧凑上下文。 |
| `list_conclusions` | 列出已保存的结论。 |
| `delete_memory` | 软删除一个内存或结论，依据 ID。 |
| `ask_memory` | 返回相关上下文，或使用 `PATHMARK_CHAT_COMMAND` 合成。 |
| `chat` | `ask_memory` 的聊天兼容别名；返回检索的上下文，以便客户端可以显示已使用的内容。 |
| `get_config` | 显示本地存储配置。 |
## 快速入门
```bash
npm install -g pathmark
```
然后将 MCP 服务器添加到你的客户端。
对于普通安装，优先使用 npm。要直接测试当前的 GitHub `main` 分支：
```bash
npm install -g --install-links=true github:hacksurvivor/pathmark
```
为你的代理生成设置代码段：
```bash
pathmark setup list
pathmark setup claude-code
pathmark setup opencode --json
pathmark setup gemini-cli
pathmark setup kimi
```
参见 [docs/compatibility.md](docs/compatibility.md)，了解 Codex、Claude Code、opencode、Gemini CLI、OpenClaw、Hermes Agent、Grok CLI、Kimi、GLM 和通用 MCP 设置。
### Codex
```bash
codex mcp add pathmark -- pathmark
```
Codex 用户也可以启用自动捕获：
```bash
pathmark codex install --replace-legacy-hooks
```
### Claude Code
```bash
claude mcp add pathmark -- pathmark
```
### opencode / Gemini CLI
使用生成的代码段：
```bash
pathmark setup opencode
pathmark setup gemini-cli
```
### Claude Desktop
将以下内容添加到你的 Claude Desktop MCP 配置中：
```json
{
"mcpServers": {
"pathmark": {
"command": "pathmark",
"env": {
"PATHMARK_STORE_DIR": "~/.pathmark/memory"
}
}
}
}
```
### Cursor
将相同的命令添加到 Cursor 的 MCP 服务器设置中：
```json
{
"mcpServers": {
"pathmark": {
"command": "pathmark"
}
}
}
```
## 本地开发
```bash
npm install
npm run build
npm run smoke
```
直接运行：
```bash
PATHMARK_STORE_DIR=.pathmark npm run dev
```
## 导入旧内存
Pathmark 可以导入兼容的本地 JSONL 内存存储，而不会删除或移动源文件：
```bash
npm run import:legacy -- --source-dir ~/old-codex-memory
```
默认值：
```text
旧源： ~/.pathmark/legacy/codex
Pathmark 目标： ~/.pathmark/memory/memory.jsonl
```
导入器在写入之前创建 `memory.jsonl.backup-*` 文件，使用确定性 ID 以避免重复，并隐藏明显的 `KEY=...`、`TOKEN=...`、`PASSWORD=...` 和 `Bearer ...` 值。
在迁移另一台机器时，先进行一次干预运行：
```bash
npm run import:legacy -- --source-dir ~/old-codex-memory --dry-run
```
## Codex 自动捕获
将 Pathmark 安装为 Codex 内存适配器：
```bash
pathmark codex install --replace-legacy-hooks
```
这会注册 Pathmark MCP 服务器，启用 Codex 钩子，并删除 Codex 中的旧兼容钩子命令。它不会删除或移动内存文件。
当您希望 Pathmark 钩子接管早期兼容的钩子命令时，请使用 `--replace-legacy-hooks`。如果没有，Pathmark 将与现有的钩子命令一起安装。
检查适配器状态：
```bash
pathmark codex status
```
状态输出为 JSON，包含 Pathmark 钩子状态、MCP 注册状态、旧钩子存在、活动存储路径和当前记录计数。
删除 Pathmark 钩子和 MCP 注册，同时保留内存：
```bash
pathmark codex uninstall
```
## 配置
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `PATHMARK_STORE_DIR` | `~/.pathmark/memory` | `memory.jsonl` 的目录。 |
| `PATHMARK_MAX_SEARCH_RESULTS` | `12` | 默认搜索限制。 |
| `PATHMARK_SYNTHESIS_PROVIDER` | `client` | `client`、`command`、`codex` 或 `openai-compatible`。 |
| `PATHMARK_CHAT_COMMAND` | 未设置 | 命令提供者：接收标准输入的综合提示并在标准输出上写入答案。 |
| `PATHMARK_CODEX_COMMAND` | `codex` | Codex 提供者命令。 |
| `PATHMARK_CODEX_MODEL` | 未设置 | 可选的 Codex 模型覆盖。 |
| `PATHMARK_OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI 兼容的 API 基本 URL。 |
| `PATHMARK_OPENAI_API_KEY` | 未设置 | OpenAI 兼容的 API 密钥。 |
| `PATHMARK_OPENAI_MODEL` | 未设置 | OpenAI 兼容的合成模型 ID。 |
| `PATHMARK_CHAT_TIMEOUT_MS` | `120000` | 合成命令超时。 |
## 合成模式
Pathmark 将内存与推理分开。
### `client`
默认。MCP 服务器返回相关的内存上下文，您的 MCP 客户端模型合成答案。这适用于 Codex、Claude Desktop、Cursor 和任何其他 MCP 客户端，无需向 Pathmark 提供模型凭证。
```bash
PATHMARK_SYNTHESIS_PROVIDER=client pathmark
```
### `command`
使用任何本地订阅或模型 CLI，接受标准输入的提示并在标准输出上写入答案：
```bash
PATHMARK_SYNTHESIS_PROVIDER=command \
PATHMARK_CHAT_COMMAND="your-ai-cli --model your-model" \
pathmark
```
这是用户拥有其他付费订阅 CLI 或本地模型运行器的常规路径。
### `codex`
使用经过验证的 Codex CLI 桥。它运行一个受控的、非交互式的 `codex exec` 转换，禁用钩子和内存以避免递归：
```bash
PATHMARK_SYNTHESIS_PROVIDER=codex \
PATHMARK_CODEX_MODEL=gpt-5.5 \
pathmark
```
这对拥有 ChatGPT/Codex 订阅身份验证的 Codex 用户很有用，但他们不想添加 OpenAI API 密钥。
### `openai-compatible`
使用任何提供 `/chat/completions` 的服务，包括许多 Kimi、GLM/Z.ai、OpenRouter、LiteLLM、Ollama 兼容网关和自托管路由器：
```bash
PATHMARK_SYNTHESIS_PROVIDER=openai-compatible \
PATHMARK_OPENAI_BASE_URL=https://api.provider.example/v1 \
PATHMARK_OPENAI_API_KEY=... \
PATHMARK_OPENAI_MODEL=... \
pathmark
```
此模式仅影响 `ask_memory`。常规 MCP 工具仍在本地存储和检索内存，无需模型提供者。
## 设置 CLI
`pathmark setup <client>` 为常见外壳打印复制粘贴设置。添加 `--json` 时，您需要脚本的结构化输出。
支持的目标：
```text
codex
claude-code
claude-desktop
cursor
opencode
gemini-cli
generic
openai-compatible
command
```
别名包括 `claude`、`gemini`、`kimi`、`glm` 和 `z-ai`。
## 数据格式
Pathmark 在以下位置存储换行分隔的 JSON：
```text
~/.pathmark/memory/memory.jsonl
```
每个记录都是可检查的：
```json
{
"id": "uuid",
"kind": "memory",
"text": "用户更喜欢本地优先工具。",
"tags": ["preference"],
"source": "mcp",
"createdAt": "2026-06-29T00:00:00.000Z",
"updatedAt": "2026-06-29T00:00:00.000Z"
}
```
删除是软删除：记录获取一个 `deletedAt` 时间戳。
## 路线图
- Codex、Claude Code、opencode、Gemini CLI 和其他 MCP 客户端的安装程序。
- 每个外壳的可选自动捕获钩子/导入器，以便在提示较少的情况下保存有用上下文。
- 常见本地 AI CLI 的提供者预设，其中存在稳定命令。
- 其他内存系统的导入/导出命令。
- 使用可选本地嵌入的更好排名。
- 项目、团队和客户端的命名空间。
- 加密存储选项。
- 作为可选层的托管同步，而不是必需项。
- Codex、Claude Desktop、Cursor、ChatGPT 和本地 LLM 工具的示例配方。
## 定位
Pathmark 为您的代理提供了一个共享的工作内存，该内存保留在您的机器上。
> 切换代理。保持上下文。
> 自带订阅。保留本地内存。
## 许可证
MIT
