pith-core

<!-- mcp-name: io.github.pithrun/pith --> # Pith — AI 智能代理记忆与认知治理 [](LICENSE) [](https://python.org)  > 为 AI 智能代理提供受控的记忆，适用于跨模型的持续项目上下文、矛盾检测、持久学习和会话检查点。 ## 为什么选择 Pith？ AI 智能代理是无状态的。每次对话都从零开始。Pith 解决了这个问题。 Pith 作为一个本地记忆服务，为支持的 AI 开发工作流运行。它捕获智能代理在对话过程中学习的内容 — 做出的决定、发现的模式、建立的原则 — 并在需要时检索这些知识。随着时间的推移，您的 AI 发展出真正的连续性：它记住架构决策、偏好和项目上下文。 **AI 堆栈有三个层。Pith 专注于认知治理层。** | 层 | 构建者 | 没有它 | |---|---|---| | 安全治理 — 控制智能代理可以访问的内容 | Microsoft、Rubrik、Cisco | 未授权访问 | | 存储和回忆 — 存储智能代理看到的内容 | Mem0、Zep、Letta、Anthropic | 失忆 | | **认知治理 — 控制智能代理应该相信的内容** | **Pith** | **过时的信念、矛盾、漂移** | ## Pith 与其他记忆工具的比较（来源：2026 年 6 月 10 日） | 焦点 | Pith | Mem0 | Zep / Graphiti | Letta | |---|---|---|---|---| | 公共定位 | 用于 AI 智能代理的受控本地项目记忆：决策、纠正、矛盾和受信任的上下文跨会话传递 | 通用、自改进的记忆层，用于 LLM 应用 | 用于智能代理的时间知识图和上下文图平台 | 用于具有记忆和学习功能的智能代理的平台和工具 | | 随时间变化 | 跟踪信念生命周期、矛盾、衰减和权威，以便智能代理可以修订过时的项目知识，而不是简单地检索它 | 持久记忆、用户/上下文适应和记忆操作 | 时间事实、来源和演变的图上下文 | 持久智能代理状态、记忆块和基于记忆的智能代理工作流 | | 本地/自托管路径 | 本地 SQLite 支持的开发者预览版；您的记忆数据库保留在您的机器上，而支持的客户端通过本地 API/MCP 工作流连接 | 开源软件包和自托管 REST API 文档 | Graphiti 开源；Zep 平台单独提供 | 开源项目，具有本地和托管部署路径 | | 启动比较立场 | 最适合解决受控的本地项目连续性问题：保存决策和纠正、解决冲突的知识并防止过时的记忆影响未来工作 | 邻近的记忆层 | 邻近的时间图记忆 | 邻近的具有状态的智能代理平台 | 来源：[Mem0 文档](https://docs.mem0.ai/introduction)、[Mem0 OSS REST API](https://docs.mem0.ai/open-source/features/rest-api)、[Graphiti 文档](https://help.getzep.com/graphiti/getting-started/overview)、[Letta](https://www.letta.com/) 和 [Letta GitHub](https://github.com/letta-ai/letta)。 ## 基准测试 Pith 在 MemoryAgentBench / FactConsolidation 和 LoCoMo-Plus 官方认知 all401 中有得分证据。在 LoCoMo-Plus 官方认知 all401 中，Pith 记录了 `100.00%` 的准确率，涵盖 `401/401` 行。在 MemoryAgentBench / FactConsolidation 多跳中，Pith 记录了 6K 通道上的 `95.0%` 完全匹配和 262K 通道上的 `68.0%` 完全匹配 / `68.2` F1。截至 2026 年 6 月 12 日，这些 MAB 分数领先于已发布的 MAB / FactConsolidation 多跳比较器分数。 有关方法论、分数术语、注意事项和证据文件，请参阅 [Pith 基准测试页面](https://pith.run/benchmarks)。 ## 演示  > 安装 → 知识库统计 → 服务器状态。12 秒。[查看演练文件](demo/demo.cast) 以使用 `asciinema play demo/demo.cast` 在本地重放。 ## 快速入门 ### 先决条件 - **macOS 开发者预览版** — Pith 的初始公开预览版优先考虑 macOS。 - **Python 3.10+** — 在 macOS arm64 上，安装程序可以在 `~/.pith` 中配置一个 Pith 管理的 Python 3.12 运行时，如果没有兼容的 Python。 它不会替换或修改系统 Python。 - **支持的 AI 应用** — 验证的启动工作流包括 Claude Cowork、Claude Desktop、Claude Code、Cursor、VS Code 和 Codex。 ### macOS 开发者预览版客户端矩阵 目前，**Claude Cowork** 和 **Codex** 是完全自动化的 Pith 生命周期客户端。其他客户端可能具有验证的设置、MCP 工具访问或钩子捕获，但它们仍然需要手动指令设置、模型工具选择或证明检查，然后才能被视为完整的生命周期表面。 | 表面 | 生命周期状态 | 用户预期 | |---|---|---| | Claude Cowork | 完全自动化的 Pith 生命周期，安装 Cowork 系统提示/指令后 | Pith 管理的 Cowork 会话在 Cowork 系统提示/指令安装后自动运行完整的生命周期：预响应上下文、响应学习、检查点和会话关闭。在 Cowork 中不需要单独的本地 MCP 配置。 | | Codex 应用 | 完全自动化的 Pith 生命周期，设置 `~/.codex/AGENTS.md` 后 | Codex 使用本地 HTTP/API 生命周期路径：`conversation_turn` 在实质性响应之前，然后在生命周期边界处使用 `checkpoint` 或 `session_end`。MCP 对于健康状态仍然是可选的；`api-fallback` 仅是一个遗留/恢复别名。 | | 终端 CLI | 验证的本地操作 | `pith status`、`pith health`、`pith start`、`pith logs`、`pith doctor`、`pith clients`、`pith support bundle`、`pith import` 和备份在本地运行。 | | launchd 服务 | 验证的 macOS 自动启动 | macOS 自动启动由原生安装程序安装。 | | Claude Desktop | 验证的配置 + 手动指令步骤；默认情况下不是完全自动化的 | MCP 配置自动写入；如果您在安装过程中没有完成指令步骤，请运行 `pith protocol`，然后将复制的提示粘贴到 Claude Desktop `Settings > General > Instructions for Claude` 中。工具在重启后可用，但 Claude 决定是否在给定回合中调用它们；完整的生命周期证明需要观察到的 `pith_conversation_turn` 调用或用户明确要求 Claude 使用 Pith。 | | Claude Code | 钩子捕获 + 模型可见证明；不作为完全自动化的列出 | 钩子注册/捕获 Claude Code 回合并要求模型调用 `pith_conversation_turn`。完整的模型可见生命周期证明需要观察到的 Claude Code MCP 工具调用，而不仅仅是钩子安装。 | | VS Code | 可配置的 MCP + Copilot 指令文件；测试行为尚未等同于 Claude Cowork/Codex | 用户配置位于 `~/Library/Application Support/Code/User/mcp.json`；项目配置位于 `~/.pith/pith-server/.vscode/mcp.json`；Copilot 指令位于 `~/.copilot/instructions/pith-cognitive-loop.instructions.md`。Agent Chat 必须处于 Agent 模式并启用 Pith 工具，并且模型可能不会在每个回合中自动调用 Pith。 | | Cursor | MCP 配置模板 + 全局/用户规则步骤 | 安装程序编写 `~/.cursor/mcp.json`，在 `~/.pith/CURSOR_GLOBAL_RULE.txt` 处保存一个 Cursor 规则片段，并将其复制到剪贴板上，适用于 macOS。Cursor 可以看到 Pith 服务器，但当前的测试显示 Cursor 不会在仅凭 MCP 配置的情况下在每个回合中自动调用 Pith。将片段粘贴到 Cursor 设置 > 规则中作为全局/用户规则，或使用项目 `AGENTS.md`，直到安装程序具有验证的自动 Cursor 指令流程。 | ### 安装（5 分钟） Pith 作为 macOS 优先的开发者预览版启动。 ```bash curl -fsSL https://pith.run/install | bash ``` 较旧的 macOS 机器可能只有 Apple 的 Python 3.9。在正常的交互式安装中，Pith 将提供在其自己的 Python 运行时下安装 `~/.pith`。对于非交互式自动化，请明确选择： ```bash curl -fsSL https://pith.run/install | PITH_AUTO_PYTHON=1 bash ``` Windows 支持不属于初始开发者预览版的一部分。 安装程序处理所有内容：Python venv、依赖项、API 密钥生成、AI 应用表面选择、MCP 客户端配置、自动启动设置和健康验证。 ### 安装后 **必需设置** 1. 打开一个新的终端窗口，以便您的 shell 能够获取 `pith` 命令。 2. Claude Desktop 用户：如果您在安装过程中粘贴了 Pith 的指令，这已经完成了。如果您跳过了它或需要重新执行，请运行 `pith protocol`，然后将复制的提示粘贴到 Claude Desktop `Settings > General > Instructions for Claude` 中。相同的提示保存在 `~/.pith/SYSTEM_PROMPT.md` 中。 3. 在测试之前，请完全重启每个配置的 AI 客户端。对于 Claude Desktop，请使用 Cmd+Q / Ctrl+Q，然后重新打开。 **验证检查** 1. **核心安装：** 运行 `pith status` 并确认它报告 `Health: OK (Pith)`。 2. **Claude Cowork：** 确认 Cowork 系统提示/指令已安装并激活。之后，Pith 管理的 Cowork 会话具有内置的完整生命周期自动化；仅当您需要证据报告时才使用本地诊断。 3. **Claude Desktop / Claude Chat：** 打开一个新的对话并提出一个正常的项目上下文问题。验证 `~/Library/Logs/Claude/mcp-server-pith.log` 中的实际 `pith_conversation_turn` 调用；仅 MCP 启动证明工具可用性。如果 Claude 没有选择该工具，请明确要求 Claude 为请求使用 Pith 并验证观察到的调用。 4. **Claude Code：** 运行 `claude mcp get pith`，然后启动一个新的 Claude Code 会话。钩子应该注册该回合，但完整的证明需要观察到的模型可见的 `pith_conversation_turn` 工具调用。 5. **Codex：** 确认 `~/.codex/AGENTS.md` 存在并引用 `pith api conversation_turn`。如果 Codex 在 Pith 之后安装，请重新运行安装程序或客户端配置。 6. **VS Code：** 重启 VS Code，运行 **MCP：列出服务器**，并确认 `pith` 从 `~/Library/Application Support/Code/User/mcp.json` 出现。打开聊天诊断并确认 `~/.copilot/instructions/pith-cognitive-loop.instructions.md` 已为 Agent Chat 加载。如果 Agent Chat 表示 Pith 未连接但可以找到活动服务器/配置，请将其视为 VS Code 工具选择/指令加载问题，而不是失败的 Pith 服务。 ### 验证 ```bash pith status # 显示“running” + 健康状态 OK pith stats # 显示概念计数、知识领域、数据库大小 scripts/macos-surface-smoke.sh # macOS 表面库存和烟雾报告 ``` ## 它是如何工作的 Pith 作为一个本地 Python 服务，具有三种连接模式： - **本地 HTTP/API 生命周期：** CLI 具备能力的代理（如 Codex）可以调用 `~/.pith/bin/pith api conversation_turn --stdin-json` 在响应之前，然后在生命周期边界处调用 `checkpoint` 或 `session_end`。 - **MCP 工具桥：** 具备 MCP 功能的客户端（如 Claude Desktop 和 VS Code）可以通过 `pith_mcp.py` 连接并直接调用 `pith_` 工具，当这些工具由客户端启用时。 - **终端 CLI：** 您使用诸如 `pith status`、`pith health`、`pith start`、`pith logs`、`pith doctor`、`pith clients`、`pith support bundle`、`pith import` 和 `pith backup` 等命令管理本地服务。 在对话过程中，您的代理： 1. **检索** 相关知识后响应 2. **学习** 每次交换后的决策、模式和发现 3. **巩固** 通过定期反思和维护知识 ``` Codex / CLI 代理 ←→ pith api 命令 ←→ Pith API (FastAPI) ←→ SQLite Claude / MCP 应用 ←→ MCP 桥 ←→ Pith API (FastAPI) ←→ SQLite VS Code 代理 ←→ 启用 MCP 工具 ←→ Pith API (FastAPI) ←→ SQLite (pith_mcp.py) (localhost:8000) (pith.db) ``` Pith 在 `~/pith-data/` 处本地存储和提供数据。当 AI 客户端在对话中使用检索的上下文时，该客户端可能会根据其设置和条款将对话内容发送到其配置的模型提供商下。 ## CLI 参考 | 命令 | 描述 | |---------|-------------| | `pith start` | 启动 Pith 服务器 | | `pith stop` | 停止服务器 | | `pith restart` | 重启服务器 | | `pith status` | 检查运行状态 + 健康状态 | | `pith health` | 检查操作健康状态/就绪状态 | | `pith stats` | 快速知识总结 | | `pith logs` | 尾随服务器日志（跟随模式） | | `pith logs snapshot` | 打印有界的删减日志快照 | | `pith doctor` | 运行只读安装和服务诊断 | | `pith clients` | 显示检测到的配置客户端表面 | | `pith support bundle` | 创建删减的支持包 | | `pith import` | 安全导入对话导出 | | `pith api` | CLI 具备能力的代理的优先 HTTP/API 生命周期调用 | | `pith api-fallback` | 本地 HTTP/API 生命周期路径的遗留/恢复别名 | | `pith backup` | 创建 WAL 安全的数据库备份 | | `pith restore` | 从最近的备份恢复 | | `pith update` | 更新 Pith 到最新版本 | | `pith version` | 显示版本和系统信息 | | `pith report` | 完整的诊断报告 | | `pith profiles` | 列出可用的配置文件 | | `pith maintenance run` | 运行维护周期 | | `pith uninstall` | 完全删除 Pith | 所有命令都支持 `--profile NAME` 用于多配置文件设置。 ## 备份您的数据 Pith 通过自动和手动备份保护您的知识库。 **自动备份** 每 6 小时作为维护周期的一部分运行。服务器使用 Python 的 `sqlite3.Connection.backup()` 创建一个 WAL 安全的副本，位于 `~/pith-data/{profile}/pith_backup.db` 处 - 没有服务器停机时间，没有 WAL 损坏风险。您可以随时检查备份健康状况： ```bash curl -s http://localhost:8000/health/backup | python3 -m json.tool ``` `/health/backup` 端点返回状态（`healthy`、`warning`、`critical`）、备份年龄、完整性检查和概念计数 — 适用于监控仪表盘。 **可选的 webhook 警报：** 设置 `PITH_BACKUP_ALERT_WEBHOOK_URL` 环境变量以在备份失败时接收警报。警报使用渐进的冷却（2h → 6h → 24h）以避免通知疲劳。适用于 Slack、Discord 或任何 webhook 端点。 **手动备份** 提供带时间戳的快照： ```bash pith backup # WAL 安全，适用于服务器运行时 pith restore # 从最近的备份恢复 pith restore ~/my_backup.db # 从特定文件恢复 ``` 手动备份保存在 `~/pith-data/{profile}/backups/` 处，并带有时间戳。macOS 安装程序还会在 2:00 AM 处设置自动每日备份。 > **重要：** 永远不要直接复制 `pith.db`，而是使用 `pith backup` 或让自动备份处理它。 ## 多配置文件支持 Pith 支持多个隔离实例用于不同上下文： ```bash pith --profile work start # 用于工作的单独知识库 pith --profile personal start -> 用于个人知识库的单独知识库 pith profiles # 列出所有配置文件并显示数据库大小 ``` 每个配置文件在 `~/pith-data/{name}/` 处拥有自己的数据库、索引、备份和日志。 ## 故障排除 **您的 MCP 客户端中没有显示 Pith 工具？** - 完全重启您的客户端（Cmd+Q，不要只是关闭窗口） - 检查您的 MCP 配置文件是否有 Pith 服务器条目和正确的路径 - Claude Desktop：`cat ~/Library/Application\ Support/Claude/claude_desktop_config.json` - VS Code：`cat ~/Library/Application Support/Code/User/mcp.json`；然后运行 **MCP：列出服务器** 并从 `~/Library/Application Support/Code/User/mcp.json` 启动 `pith` - Cursor：检查 `~/.cursor/mcp.json` **Cursor 看到了 Pith 但不自动调用它？** - 打开 Cursor 设置 > 规则并添加一个全局/用户规则，告诉 Cursor 在实质性响应之前调用 Pith。 - 安装程序在 macOS 上将一个启动器规则保存在 `~/.pith/CURSOR_GLOBAL_RULE.txt` 处并将其复制到剪贴板。 - 如果您更喜欢基于项目的说明，请将 Pith 认知循环添加到项目 `AGENTS.md`。 - 将 `~/.cursor/mcp.json` 视为工具可用性，而不是强制执行自动生命周期。 **VS Code 看到了配置，但说 Pith 未连接？** - 确认您正在使用代理模式，而不是纯粹的 Ask/Edit 聊天。 - 在聊天输入处打开 **配置工具** 并为请求启用 Pith MCP 工具。 - 运行 **MCP：列出服务器** 并启动或重启 `pith` 服务器（如果需要）。 - 打开聊天诊断并确认 Pith 指令文件已加载。对于 Agent Chat 而言，VS Code MCP 的可用性意味着工具可用，但不能保证模型会在每个回合中调用它们。 **Claude Desktop / Claude Chat 列出了 Pith 但不总是调用它？** - 运行 `pith protocol` 并将提示粘贴到 Claude Desktop `Settings > General > Instructions for Claude`。 - 重启 Claude Desktop 并启动一个新的对话。 - `tools/list` 或 `resources/list` 在 `~/Library/Logs/Claude/mcp-server-pith.log` 中仅证明了 MCP 启动。600 秒的空闲传输关闭可以是正常的桥接生命周期噪音。缺少 `pith_conversation_turn` 通常意味着自定义指令未激活或模型未选择生命周期工具；您可以明确要求 Claude 为请求使用 Pith，然后验证观察到的调用。 **Claude Cowork 生命周期未触发？** - 首先确认 Cowork 系统提示/指令已安装并激活。之后，Cowork 是具有完全生命周期自动化的托管表面；任何缺少的生命周期事件都应被视为服务或会话路由问题，而不是本地 MCP 配置问题。 **API 未响应？** - 检查状态：`pith status` - 检查端口：`lsof -ti:8000` - 重启：`pith restart` **端口 8000 被占用？** - 检查它是否是 Pith：`pith status` - 检查监听器：`lsof -nP -iTCP:8000 -sTCP:LISTEN` - 如果它是一个陈旧的 Pith 进程，请运行 `pith restart`。如果它是另一个应用程序，请停止该应用程序或在启动 Pith 之前选择不同的端口。 ## 支持 Pith 是一个免费的开源开发者预览版。 - 本地开发者预览版没有活跃的 Pith 使用限制。 - 诊断中显示的价格或预算字段保留用于未来或显式启用的环境；它们在公共预览版中默认情况下不活跃。 - 错误和设置问题：使用 GitHub Issues。 - 安全漏洞：发送电子邮件至 security@pith.run。 - 创始人主导的入职培训或团队试点：发送电子邮件至 info@pith.run。 支持在开发者预览期间为尽力而为。 ## 许可 Apache 2.0 — 请参阅 [LICENSE](LICENSE) 以获取条款。 版权 (c) 2026 Andrew Estey-Ang.