Pathmark

Pathmark

在不同 Agent 之间传递意图，而不把过时的代码事实变成隐秘记忆。

新增内容 — v0.1.17

Pathmark v0.1.17 不再让 Claude Code 对每次记忆查找都进行权限拦截：

• pathmark setup claude-code --apply-permissions 会为 Pathmark 的十个本地只读工具添加允许规则，使回忆和搜索无需权限提示即可运行；在自动模式下，也无需经过可能暂时失败的安全分类器往返流程；
• 此命令会备份 ~/.claude/settings.json，仅添加缺少的规则，保留其他所有设置，且绝不会重写无法解析的文件；
• 允许列表会依据工具自身的 readOnlyHint/openWorldHint 注解进行测试，因此任何会写入、删除或可能调用外部模型的操作仍会保留权限提示。

请参阅 v0.1.17 发行说明或完整的变更日志。上方的 npm 徽章始终显示当前已发布的版本。

Pathmark 为 Codex、Claude Code、opencode、Gemini CLI、Cursor 以及任何支持 MCP 的框架提供一个本地意图与来源信息层。只需保存一次决策、约束、偏好和已批准的结论，即可让下一个 Agent 使用，无需粘贴回顾内容。

代码记住实现方式。Pathmark 记住意图。 仓库代码、架构、测试、CI 和有意编写的 Agent 指令，仍然是软件工作方式的权威依据。原始会话是可搜索的证据，而非自动可信的事实。

你的上下文保存在磁盘上的 ~/.pathmark/memory/memory.jsonl。开始使用无需账号、托管数据库、API 密钥或供应商后端。

OpenAI Build Week 2026

Pathmark 是 OpenAI Build Week 2026 的 开发者工具 参赛项目。该项目在挑战赛开始前便已存在，因此本次参赛有意限定为报名期于 2026 年 7 月 13 日开启后开发的实质性扩展。

在符合资格的期间，Codex 与 GPT-5.6 协助审查并扩展 Pathmark，将其从可运行的本地记忆层升级为更安全的长期开发者基础设施：

• 修复了复现出的多进程 SQLite 索引竞态；
• 添加了修订历史、取代、过期、保留策略、诊断、备份、压缩以及预览优先的彻底清除功能；
• 添加了按命名空间限定的读写功能，以及默认的敏感信息脱敏功能；
• 添加了范围限定的导入/导出、可选的 AES-256-GCM 可移植导出、本地混合重排序以及可移植的框架数据导入；
• 加固了 CI 和 npm 发布流程，加入必需的 CodeQL 和依赖项审查、不可变 Action 引用、受保护的标签、OpenSSF 分析以及 SLSA 来源证明。

本次工作的主要 Codex 会话为 019f5fc3-d7e6-7b41-8a30-d161c90b98fb。符合条件的发行版本范围为 v0.1.6 至 v0.1.7；挑战赛开始前的基线为提交 4c0e87dfdbd2ba4c643abd8b887cc228bdb08b73。

请参阅 Build Week 实施记录，了解前后范围界定、提交证据、Codex 协作详情以及快速评审测试。

为什么选择 Pathmark

你不会只用一种工具。你让 Codex 修复问题，让 Claude Code 进行审查，让 opencode 清理代码，让 Gemini CLI 挑战方案。除非你在工具之间传递上下文，否则每种工具启动时都一无所知。

Pathmark 为这些工具提供一个读写意图和证据的统一位置：

• 所有工具框架共用一个本地 JSONL 存储。
• 标准 MCP 工具包括 remember、search_memory、recall_memory、session_trace、rate_recall、consolidate_memory、audit_memory，以及结论优先的 chat / ask_memory。
• 默认由客户端进行综合，因此由你的编码 Agent 读取上下文并作答。
• 可选的 Codex CLI、本地命令和 OpenAI 兼容的综合模式。
• 纯文本文件，可供检查、备份、删除或迁移。

Pathmark 保持与提供商无关。Codex 提供一个可选的综合预设。核心服务可与任何能使用本地工具的 MCP 客户端配合使用。

Pathmark 需要 Node.js 22.5 或更高版本。

跨工具框架记忆

你会在编码会话中切换工具：

• Codex 修复失败的测试。
• Claude Code 审查补丁。
• opencode 清理差异。
• Gemini CLI 挑战方案。

Pathmark 将这些笔记保存在同一个存储中。

将每种工具框架指向同一个存储：

Codex       \
Claude Code \
opencode     >  Pathmark MCP  >  ~/.pathmark/memory/memory.jsonl
Gemini CLI  /
Cursor     /

在每种工具框架中安装 Pathmark，并将它们指向同一个 PATHMARK_STORE_DIR。一个工具可以用 remember 保存原始上下文，或用 create_conclusion 提出一条持久结论；随后可以通过 recall_memory、search_memory、get_context 或 ask_memory 找回已批准的结论和原始证据。

Pathmark 位于 Agent 之下，作为编码工作流的意图、证据和来源总线。

工具

Pathmark 提供以下 MCP 工具：

工具	用途
remember	保存可搜索的原始证据。原始证据不会被视为已批准的持久意图。
create_conclusion	提出信号更强的持久结论或偏好。默认情况下，必须先获得批准才能检索。
search_memory	搜索记忆和结论。
recall_memory	透明检索：返回上下文以及所用记忆的确切 ID、时间戳、来源、匹配项、标签和预览。接受可选的 tags、精确的 ids，以及精简输出选项 includeRecords: false。
session_trace	返回一个会话范围受限的时间顺序审计记录：提示词、注入的确切记忆 ID、已脱敏的工具输入/结果以及回答。
rate_recall	将 chat / ask_memory 检索中的确切 ID 标记为相关或不相关，以衡量审计精度。
get_context	返回任务或问题的精简上下文。
list_conclusions	列出已批准并保存的结论。
list_pending_conclusions	分页审查数量受限的待处理结论提案。
approve_conclusion	原子式批准提案，可选择更正文本/标签并记录审核者。
reject_conclusion	在审计记录中保留被拒绝的提案，同时将其永久排除在检索范围之外。
get_memory_snapshot	根据已批准的规范结论生成范围受限的 USER/PROJECT/AGENT 快照。
consolidate_memory	审查一批范围受限的未综合证据，并可选择暂存有证据支持的提案。不会自动批准任何内容。
delete_memory	按 ID 软删除记忆或结论。
update_memory	更正记录，同时保留先前版本。
supersede_memory	用一条关联的当前记录替换过时记录。
purge_memory	按 ID、命名空间、标签、来源或日期预览或执行永久删除。
audit_memory	衡量捕获到检索的行为、未使用的记录、检索时效、重复项、过时的原始命中项，以及是否存在精度标签。
doctor_memory	报告重复项、已删除/过期记录、结论和索引健康状况。
compact_memory	预览或执行去重、保留和物理清理，并自动创建备份。
backup_memory	创建某个时间点的规范 JSONL 备份。
export_memory	导出范围受限、可合并的 JSONL 数据包，可选择加密。
ask_memory	返回基于已批准结论的回答，或范围受限的原始上下文、确切溯源信息以及用于反馈的检索 ID。
chat	与聊天兼容的 ask_memory 别名，包含多意图结论检索和明确弃答。
get_config	显示本地存储配置。

快速开始

npm install -g pathmark

然后将 MCP 服务添加到客户端。

常规安装建议使用 npm。若要直接测试当前 GitHub main 分支：

npm install -g --install-links=true github:hacksurvivor/pathmark

为你的运行环境生成配置片段：

pathmark setup list
pathmark setup claude-code
pathmark setup opencode --json
pathmark setup gemini-cli
pathmark setup kimi

有关 Codex、Claude Code、opencode、Gemini CLI、OpenClaw、Hermes Agent、Grok CLI、Kimi、GLM 和通用 MCP 设置，请参阅 docs/compatibility.md。

Codex

codex mcp add pathmark -- pathmark

Codex 用户也可以启用自动捕获：

pathmark codex install --replace-legacy-hooks

如果你希望在 Codex、Claude Code、Cursor、opencode、Gemini CLI、兼容 Grok 的 MCP 宿主或任何其他 MCP 运行环境中看到“使用了哪些记忆？”这一条目，请在回答前调用 recall_memory 工具。Codex 会话开始时会注入已批准结论的快照。对于重要提示词，Codex 会先检索已批准的结论，并仅在必要时将最新的范围受限原始证据用作有限的后备信息。recall_memory 仍是在不同运行环境间通用的可见追踪方式。

Claude Code

claude mcp add --scope user pathmark -- pathmark
pathmark setup claude-code --apply-permissions

第二条命令允许 Pathmark 的本地只读工具（回忆、搜索、诊断）在无需权限提示的情况下运行，包括自动模式；否则，这些工具会等待安全分类器处理。它会备份 ~/.claude/settings.json，只添加缺失的允许规则，其他内容一律保持不变。写入或删除记忆的工具仍会请求权限。

--scope user 会让 Pathmark 在每个项目中都可用；Claude Code 的默认作用域仅覆盖当前目录。若要启用自动捕获和会话启动时的回忆（包括上下文压缩后），请将 pathmark setup claude-code 生成的 hooks 块合并到 ~/.claude/settings.json 中。

Claude Code 内置的自动记忆存储在其他 Agent 无法访问的各项目文件夹中。将其作为证据导入共享存储（可重复运行；编辑会在原位置更新并保留历史记录，而你在 Pathmark 中删除的记录会继续保持删除状态）：

pathmark import-native claude-code --dry-run
pathmark import-native claude-code

opencode / Gemini CLI

使用生成的代码片段：

pathmark setup opencode
pathmark setup gemini-cli

Claude Desktop

将以下内容添加到 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "pathmark": {
      "command": "pathmark",
      "env": {
        "PATHMARK_STORE_DIR": "~/.pathmark/memory"
      }
    }
  }
}

Cursor

将相同的命令添加到 Cursor 的 MCP 服务设置中：

{
  "mcpServers": {
    "pathmark": {
      "command": "pathmark"
    }
  }
}

本地开发

npm install
npm test
npm run coverage

直接运行：

PATHMARK_STORE_DIR=.pathmark npm run dev

导入旧版记忆

Pathmark 可以导入兼容的本地 JSONL 记忆存储，不会删除或移动源文件。

npm run import:legacy -- --source-dir ~/old-codex-memory

默认值：

Legacy source:   ~/.pathmark/legacy/codex
Pathmark target: ~/.pathmark/memory/memory.jsonl

导入器会在写入前创建 memory.jsonl.backup-* 文件，使用确定性 ID，使重复运行时跳过重复项，并对明显的 KEY=...、TOKEN=...、PASSWORD=... 和 Bearer ... 值进行脱敏。 它使用与实时 MCP 和 Codex 写入方相同的存储锁，因此导入不会覆盖并发捕获的记录。

迁移到另一台机器时，请先试运行：

npm run import:legacy -- --source-dir ~/old-codex-memory --dry-run

Codex 自动捕获

将 Pathmark 安装为 Codex 记忆适配器：

pathmark codex install --replace-legacy-hooks

这会注册 Pathmark MCP 服务、启用 Codex hooks，并从 Codex 中移除旧的兼容 hooks 命令。不会删除或移动记忆文件。

Codex 适配器默认会主动运行：

• 用户提示词、助手的最终回答和工具活动会在本地捕获；中间的 Codex 评论不在捕获范围内；
• 工具活动记录包含有界且经过脱敏的输入预览及其哈希、状态、退出代码、耗时，以及钩子提供的变更文件；
• 工具输出哈希会被捕获以供关联，而输出文本默认保持私密，只有设置 PATHMARK_CODEX_CAPTURE_TOOL_OUTPUTS=on 才会捕获；
• 活动记录会在 30 天后过期，默认最多保留 5,000 条记录；
• 会话开始或恢复时，会根据已批准的规范结论生成一份有界的 USER/PROJECT/AGENT 快照，不会注入原始会话历史；
• 每条非简单的用户提示词都会先搜索已批准的工作区／项目结论，然后搜索已批准的全局结论或明确指定项目的结论；
• 仅当没有匹配的已批准结论时，才会从当前工作区／项目／会话中注入至多两条原始记录，作为高置信度回退内容；
• 原始回退记录必须在单独的自动回忆期限内，默认为 30 天；完整的原始存档仍可通过显式调用 search_memory 和 recall_memory 获取；
• 不会自动注入跨项目的原始历史记录；如需保留长期有效的跨项目意图，请通过审批工作流将其提升为结论；
• 可通过显式调用 search_memory / recall_memory 获取广泛的跨项目历史记录，而不会在不提示的情况下将其加入每条提示词；
• 默认会静默注入匹配的记忆，不会向对话中添加原始的 recall_memory 工具结果；
• 调试或审计时，设置 PATHMARK_CODEX_VISIBLE_RECALL=on，让 Codex 使用精确的捕获前结果 ID 和工作区标签调用 recall_memory；此显式模式不会包含冗余的完整 records 副本；
• 旧版传输信封和助手进度更新不会出现在会话开始结果和主动相关性结果中，而实时委派信封仅保留当前的 <input> 负载；
• 包含 Pathmark 边界转义、指令覆盖模式或不可见 Unicode 控制字符的记录会被标记为 memory-quarantined，并从自动回忆中排除；注入的预览内容会经过转义，并明确视为不可信的历史数据；
• 没有匹配的记忆时，不会注入额外上下文。

默认情况下，持久化内容提取需要审批。create_conclusion 会创建待处理提案；待处理和已拒绝的结论会保留在规范 JSONL 审计记录中，但在结构上会被排除在常规搜索、精确 ID 回忆、提示词注入和快照之外。使用 list_pending_conclusions，然后调用 approve_conclusion 或 reject_conclusion。为保证向后兼容，在此工作流启用之前创建的结论会视为已批准。原始 remember 记录仍可作为证据搜索，不会自动提升为结论。

会话快照根据同一规范存储生成，而非单独维护为另一个扁平文件。快照会在会话开始钩子输出时冻结；提示词阶段的限定范围回忆仍会动态执行。

如果希望 Codex 钩子继续捕获记忆，但停止在提示词阶段进行回忆，请设置 PATHMARK_CODEX_PROACTIVE_RECALL=off。 只有在需要显式调用 recall_memory 工具进行审计／调试时，才设置 PATHMARK_CODEX_VISIBLE_RECALL=on。关闭此项时，提示词阶段的主动回忆仍会启用。 recall_memory 是回答前使用的记忆在某个时间点的记录。它不会包含之后运行的命令。使用确切的会话 ID 调用 session_trace，即可查看按时间顺序排列的提示词 → 注入的记忆 → 工具／结果 → 最终回答轨迹。明确启用后，输出预览会限制在 2,000 个字符以内，并在存储前进行脱敏；默认情况下，哈希值会保留关联性，而不存储输出文本。升级现有游标时，会迁移为仅解析最终回答，且不会重复记录之前捕获的用户对话或最终回答。在原始记录可用时，此迁移会按时间戳和文本软删除确切的旧版 phase: "commentary" 记录。

当你希望 Pathmark 钩子接管此前兼容的钩子命令时，请使用 --replace-legacy-hooks。否则，Pathmark 会与现有钩子命令并行安装。

检查适配器状态：

pathmark codex status

状态输出为 JSON，包含 Pathmark 钩子状态、MCP 注册状态、旧版钩子的存在情况、活动存储路径以及当前记录数。

移除 Pathmark 钩子和 MCP 注册，但不删除记忆：

pathmark codex uninstall

配置

变量	默认值	描述
PATHMARK_STORE_DIR	~/.pathmark/memory	memory.jsonl 的目录。
PATHMARK_MAX_SEARCH_RESULTS	12	默认搜索结果上限。
PATHMARK_CODEX_PROACTIVE_RECALL	on	在非简单 Codex 提示词之前，自动注入相关的 Pathmark 上下文。使用 off 可在不进行提示词时召回的情况下捕获内容。
PATHMARK_CODEX_VISIBLE_RECALL	off	选择启用用于审计/调试的 recall_memory 工具调用，以显示确切的 usedMemories。关闭此选项时，主动记忆注入仍会启用。
PATHMARK_CODEX_CAPTURE_TOOL_OUTPUTS	off	存储经过限制和脱敏的工具输出预览。关闭此选项时，仍可获取输出哈希、状态、耗时和退出代码。
PATHMARK_CODEX_MEMORY_SNAPSHOT	on	在 Codex 会话开始/恢复时，生成一份经过限制的已批准结论快照。
PATHMARK_SNAPSHOT_CHARS	4000	生成快照的字符预算；限制在 500–12000 之间。
PATHMARK_CODEX_RAW_RECALL_DAYS	30	提示词时原始证据的可用期限。0 会禁用自动原始记录回退，但不会删除或隐藏显式搜索结果。
PATHMARK_CODEX_RAW_RECALL_LIMIT	2	没有匹配的已批准结论时，注入的最新原始记录数上限。限制在 0–2 之间。
PATHMARK_CODEX_PROACTIVE_CONSOLIDATION	on	会话开始时，如果限定范围内的原始历史记录不断累积但尚无结论，则提示 Codex 审查一批经过限制的证据。
PATHMARK_CONSOLIDATION_MIN_EVIDENCE	8	显示主动整合提示前，至少需要的未合成用户/助手记录数。
PATHMARK_CONCLUSION_APPROVAL	on	将新结论暂存，等待显式批准。仅在可信的旧版自动化中设为 off。
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_NAMESPACE	未设置	一致应用于 MCP 读取和写入操作的默认命名空间。
PATHMARK_REDACT_MCP_WRITES	on	在 remember、结论、更新、取代、导入和摄取操作中，对常见的密钥类值进行脱敏。
PATHMARK_RETENTION_DAYS	0	压缩时使用的保留策略；0 会禁用按时间移除。结论会保留。
PATHMARK_ACTIVITY_RETENTION_DAYS	30	召回/工具活动记录的自动保留期限；0 会禁用按时间过期清理活动记录。
PATHMARK_ACTIVITY_MAX_RECORDS	5000	活动记录的物理上限；系统会自动移除最旧的活动记录。0 会禁用数量上限。
PATHMARK_RERANK_COMMAND	未设置	可选的可信本地嵌入/向量或混合重排器。候选项离开存储区前会应用严格的类型/标签/命名空间筛选；该命令通过标准输入接收 JSON 格式的查询/候选项，并返回排序后的记忆 ID。
PATHMARK_HYBRID_CANDIDATES	500	发送给可选重排器的候选项数上限。
PATHMARK_RETRIEVAL_TIMEOUT_MS	30000	可选重排器的超时时间。
PATHMARK_EXPORT_KEY	未设置	用于 AES-256-GCM 便携式导出/导入的密码短语。get_config 永远不会返回此值。
PATHMARK_INDEX_LOCK_TIMEOUT_MS	120000	初始化或重建索引时的跨进程等待上限。

合成模式

Pathmark 将记忆与推理分开。

client

默认模式。MCP 服务会返回相关记忆上下文，由 MCP 客户端模型综合生成答案。此模式适用于 Codex、Claude Desktop、Cursor 及任何其他 MCP 客户端，无需向 Pathmark 提供模型凭据。

PATHMARK_SYNTHESIS_PROVIDER=client pathmark

command

使用任何接受标准输入中的提示词并将答案写入标准输出的本地订阅服务或模型命令行工具：

PATHMARK_SYNTHESIS_PROVIDER=command \
PATHMARK_CHAT_COMMAND="your-ai-cli --model your-model" \
pathmark

对于使用其他付费订阅命令行工具或本地模型运行器的用户，这是通用方案。

codex

使用经过验证的 Codex 命令行桥接。它会运行受控的非交互式 codex exec，并禁用钩子和记忆以避免递归：

PATHMARK_SYNTHESIS_PROVIDER=codex \
PATHMARK_CODEX_MODEL=gpt-5.5 \
pathmark

这适用于已在本地持久保存 ChatGPT/Codex 命令行身份验证，但不想添加 OpenAI API 密钥的 Codex 用户。Pathmark 会通过标准输入发送综合提示词，在空的临时工作区中运行 Codex，忽略项目规则，并仅提供最精简的环境。记忆记录会被视为不可信数据，而非可执行指令。

openai-compatible

使用任何提供 /chat/completions 的服务商，包括许多 Kimi、GLM/Z.ai、OpenRouter、LiteLLM、Ollama 兼容网关以及可自托管的路由器：

PATHMARK_SYNTHESIS_PROVIDER=openai-compatible \
PATHMARK_OPENAI_BASE_URL=https://api.provider.example/v1 \
PATHMARK_OPENAI_API_KEY=... \
PATHMARK_OPENAI_MODEL=... \
pathmark

此模式影响 MCP ask_memory / chat 和命令行 pathmark chat。常规 MCP 工具仍可在没有模型服务商的情况下存储和检索本地记忆。

设置命令行工具

pathmark setup <client> 会打印适用于常见工具环境的可复制粘贴配置。需要脚本结构化输出时，请添加 --json。

支持的目标：

codex
claude-code
claude-desktop
cursor
opencode
gemini-cli
generic
openai-compatible
command

别名包括 claude、gemini、kimi、glm 和 z-ai。

Gemini 命令行工具的设置包含可移植的 SessionStart、BeforeAgent、AfterTool 和 AfterAgent 钩子，可自动执行限定范围的召回和捕获。其他工具环境可以通过通用导入接口传入导出的对话记录：

pathmark ingest --client=claude-code --namespace=my-project < transcript.json
pathmark ingest --client=opencode --namespace=my-project < transcript.json

记忆聊天、整合、维护和便携式同步

除非指定 --apply，否则维护命令只会预览破坏性更改：

pathmark chat "What did we decide about release signing?" --namespace=my-project
pathmark consolidate --namespace=my-project
pathmark consolidate --namespace=my-project --cursor=LAST_RECORD_ID
PATHMARK_SYNTHESIS_PROVIDER=codex pathmark consolidate --namespace=my-project --apply
pathmark feedback --recall-id=RECALL_ID --relevant=MEMORY_ID --irrelevant=OTHER_ID
pathmark audit --days=30
pathmark audit --namespace=my-project --days=90
pathmark doctor
pathmark compact
pathmark compact --apply --retention-days=90
pathmark purge --namespace=old-client
pathmark purge --namespace=old-client --apply

pathmark chat 和 MCP chat / ask_memory 工具会优先搜索已批准的结论。包含多个意图的问题可以针对不同子句返回不同结论。在默认客户端模式下，已批准的结论会生成安全的摘录式 answer；配置 codex、command 或 openai-compatible 提供方后，则可合成更丰富的文本。原始记录回退需要明确指定范围（--namespace / 标签）或 kind: memory，以防未限定范围的跨工作区历史记录进入聊天。

每次匹配到的聊天查询都会记录召回活动，并在存储可写时返回 recallId。拒绝回答和只读存储会返回 recallId: null。使用 MCP rate_recall 或 pathmark feedback，并提供准确的召回 ID，为相关性添加标签。存在反馈后，pathmark audit 会报告 precision.status: "labeled"、测得的精确率和标签覆盖率。

pathmark consolidate 会优先预览。使用默认客户端合成时，它会返回有界的证据及供宿主 Agent 使用的准确指令；宿主 Agent 可调用 create_conclusion 并提供支持证据的 evidenceIds。如果还有更多符合条件的证据，结果会包含 nextCursor 和 remainingAfterBatch；传入游标即可查看下一页稳定结果。配置服务端合成提供方后，它会预览结构化候选项；--apply 会将其暂存为待处理结论，供 approve_conclusion 或 reject_conclusion 处理。它绝不会自动批准提取出的意图。

应用压缩和清除操作会在替换规范文件前创建备份。仍可通过 delete_memory 软删除；硬清除则会从 JSONL 中物理移除所选记录，并重建派生索引。

pathmark audit 为只读操作。它会区分所有原始记录与符合整合条件的用户/助手证据，然后报告采集与召回比率、可操作的综合待办、召回时间、精确重复项、过时的原始记录命中，以及范围/缺失引用信号。除非存在明确反馈，否则精确率会保持为 unlabeled；Pathmark 绝不会用启发式结果替代用户标签。

使用有范围限制的导出和合并导入作为与传输方式无关的同步层：

pathmark export --namespace=my-project --output=project.jsonl
pathmark import project.jsonl --namespace=my-project

要使用加密便携包，请在命令行之外配置密码短语：

PATHMARK_EXPORT_KEY='use-a-secret-manager' pathmark export --encrypted --output=project.pathmark
PATHMARK_EXPORT_KEY='use-a-secret-manager' pathmark import project.pathmark

Pathmark 不会悄悄上传这些文件。请通过你选择的可信文件系统、备份工具或同步提供方来传输它们。

可选的混合检索

默认检索使用本地 SQLite FTS。若要启用语义或基于嵌入的重排，又不强制依赖模型，请将 PATHMARK_RERANK_COMMAND 设为可信的本地命令。它会通过 stdin 接收一个包含 query 和 candidates 的 JSON 对象，并且必须返回已排序记录 ID 的 JSON 数组（或 { "ids": [...] }）。如果命令失败或超时，Pathmark 会回退到词法结果。

数据格式

Pathmark 在以下位置存储以换行符分隔的 JSON：

~/.pathmark/memory/memory.jsonl

memory.jsonl 仍是规范的事实来源。Pathmark 还会维护一个派生的、可丢弃的搜索索引 memory.index.v5.sqlite。索引文件名包含架构版本，以便新旧 MCP 进程在滚动重启期间共存。JSONL 文件在 Pathmark 外部发生变化时，索引会自动重建；相关进程停止后，可以安全删除非活跃的索引版本。

每条记录都可以检查：

{
  "id": "uuid",
  "kind": "memory",
  "text": "The user prefers local-first tools.",
  "tags": ["preference"],
  "source": "mcp",
  "createdAt": "2026-06-29T00:00:00.000Z",
  "updatedAt": "2026-06-29T00:00:00.000Z"
}

默认情况下，删除采用软删除：记录会获得一个 deletedAt 时间戳。要彻底擦除数据，请先预览，再使用 purge_memory 或 pathmark purge --apply。更新会保留最多 50 个历史版本，被取代的记录会链接到其替代记录，过期记录则不会参与召回。原始自动召回时限与存储保留期限相互独立：证据可以在主动注入中因时间过久而失效，同时仍可通过显式搜索找到。

格式错误的 JSONL 行会被跳过，而不会导致所有工具崩溃。pathmark codex status 会通过 invalidRecordCount 报告此类行的数量，以便有意修复源文件。

路线图

• 为常见的本地 AI 命令行工具提供预设（前提是存在稳定的命令）。
• 加密存储选项。
• 将托管同步作为可选层，而非必需功能。
• 为 Codex 和 Gemini CLI 之外的其他框架插件系统提供原生自动捕获包。
• 为 Codex、Claude Desktop、Cursor、ChatGPT 和本地大模型工具提供示例方案。

定位

Pathmark 为你的 Agent 提供共享工作记忆，并将其保存在你的设备上。

切换 Agent，保留上下文。

使用你自己的订阅，让记忆留在本地。

作者与引用

Pathmark 由 AI 产品工程师 Sergey Moloman 创建并维护。

机器可读的作者信息和引用元数据位于 CITATION.cff 和 codemeta.json 中。

许可证

MIT