Octopoda
为 AI Agent 提供持久记忆、循环检测、审计追踪与实时看板的开源底层层。
- Star 数
- ★ 486
- 最近更新
- 2 个月前
- License
- NOASSERTION
- 主语言
- Python
- FA 评分
- 43/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台Claude Code · Claude.ai · OpenAI APIChatGPT（部分支持）
- 开始前需要
- 典型场景
- 做线上聊天机器人的开发者：进程一重启 Agent 就忘记用户姓名和偏好，改用 AgentRuntime 后 remember/recall 跨重启、崩溃和部署依然有效。
- 主要局限
- 本地语义搜索需要额外安装 octopoda[ai]（约 33 MB 嵌入模型）；未安装时 recall_similar 在本地返回 0 条结果并记录警告，行为与云端不一致。
- 源码审查
- 43/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Octopoda 是 Ryjox Technologies 推出的开源记忆与可观测性层，位于你的 Agent 与生产系统之间。它以 Python 包形式分发，pip install 后即可使用：核心类是 AgentRuntime，通过 remember/recall/log_decision 等 API 让每个 Agent 获得跨重启、崩溃和部署依然存活的版本化记忆。它内置五信号循环检测引擎（retry、oscillation、ping-pong、reflection、recall），并把每次决策、写入和恢复记录成可回放的审计时间线；通过 audit-v2 端点写入的事件还会按 Agent 做哈希链校验（prev_hash → _this_hash）。本地模式用 SQLite 存于 ~/.synrix/data/synrix.db，可零账号运行；设置 OCTOPODA_API_KEY 后同一份代码即可同步到云端 PostgreSQL + pgvector。它同时提供 LangChain、CrewAI、AutoGen、OpenAI Agents SDK 适配器，以及一个暴露 28 个工具的 MCP 服务器，可接入 Claude Code、Claude Desktop 或 Cursor。
核心入口是 AgentRuntime 与 octopoda.init()。octopoda.init(api_key=...) 会自动探测你使用哪个框架，逐轮捕获对话、提炼为记忆，并在后续调用中注入相关召回；octopoda-run python your_agent.py 可在不改动脚本的情况下完成自动埋点，octopoda-run doctor 用于检查密钥与检测到的框架。记忆 API 包括 remember、recall、recall_history、recall_similar、forget、forget_stale、consolidate、memory_health。多 Agent 场景下可用 share/read_shared 在命名空间中共享知识，并用 shared_conflicts 查看并发写冲突。循环检测在每次写入时自动运行，可介入策略（自动暂停、花费上限）通过 v2 熔断配置选择性开启。审计上，log_decision 记录决策及其当时的内存快照；审计 v2 端点 POST /v1/auditv2/event、GET /v1/auditv2/events、GET /v1/auditv2/verify-chain 提供按 Agent 的哈希链与完整性校验。快照与恢复由 snapshot/restore 完成，另有 set_goal/update_progress、send_message/read_messages 等能力。本地执行 pip install octopoda[server] 后运行 octopoda 命令，即可在 http://localhost:7842 打开与云端同款的看板。
- 做线上聊天机器人的开发者：进程一重启 Agent 就忘记用户姓名和偏好，改用 AgentRuntime 后 remember/recall 跨重启、崩溃和部署依然有效。
- 使用 LangChain、CrewAI、AutoGen 或 OpenAI Agents SDK 的团队：通过对应的 Memory 适配器类（如 LangChainMemory、CrewAIMemory）一行接入持久记忆，而无需自建向量库。
- 被 Agent 反复重试烧钱困扰的运维或负责人：用五信号循环检测定位 retry、ping-pong 等具体调用，再决定是否开启自动暂停与花费上限。
- 需要合规与事后追责的团队：把关键事件写入 audit-v2 端点获得按 Agent 的哈希链，并调用 verify-chain 验证记录未被篡改。
- 多 Agent 协作项目：通过共享记忆空间让研究 Agent 与编码 Agent 交换知识，并用冲突查询看到哪些写入发生碰撞。
- 使用 Claude Code 或 Cursor 的个人开发者：安装 octopoda[mcp] 并在客户端注册 MCP 服务器，为对话补上跨会话的持久记忆。
如何安装或部署这个 Agent？
要求 Python 3.9+（[mcp] 额外组件需要 3.10+）。按需选择：pip install octopoda（核心）；pip install octopoda[ai]（本地语义搜索嵌入，模型约 33 MB，CPU 运行）；pip install octopoda[server]（本地看板，基于 Flask）；pip install octopoda[nlp]（spaCy 知识图谱抽取）；pip install octopoda[mcp]（MCP 服务器）；pip install octopoda[all]（全部，需 Python 3.10+）。Python 3.9 上若想装除 MCP 外的全部，使用 pip install octopoda[ai,server,nlp]。本地模式无需账号，数据落在 ~/.synrix/data/synrix.db；使用云同步时运行 octopoda-init 交互式写入 ~/.octopoda/config.json，或直接设置 OCTOPODA_API_KEY（真实云端密钥以 sk-octopoda- 开头；local、offline、dev、none、YOUR_KEY_HERE 等会被当作本地哨兵值）。
如何使用这个 Agent？
最快路径：pip install octopoda 后执行 import octopoda; octopoda.init(api_key="sk-octopoda-...")，或直接以 octopoda-run python your_agent.py 启动既有脚本。不用账号的 SDK 直连方式：from octopoda import AgentRuntime; agent = AgentRuntime("my_chatbot"); agent.remember("user_name", "Alice"); 重启 Python 后调用 agent.recall("user_name").value 仍返回 'Alice'。本地看板：pip install octopoda[server] 后运行 octopoda，访问 http://localhost:7842。MCP 接入 Claude Code：pip install octopoda[mcp]，然后 claude mcp add octopoda -s user -e OCTOPODA_API_KEY=sk-octopoda-YOUR_KEY -- python -m synrix_runtime.api.mcp_server；Claude Desktop 则在 claude_desktop_config.json 的 mcpServers 下配置同样的 command 与 args。注意客户端会加上服务器名前缀，服务端 octopoda_remember 暴露为 octopoda_octopoda_remember。多脚本共享同一份记忆时设置 OCTOPODA_AGENT_ID=my-agent；网络较慢时提高 OCTOPODA_RECALL_TIMEOUT（秒）。修改 MCP 注册的环境变量后需重启 Claude Code 窗口。
这个 Agent 有哪些优点和局限？
- 本地优先：pip install 后零基础设施即可用，SQLite 落盘于 ~/.synrix/data/synrix.db，无需账号、Docker、Redis；之后靠一个环境变量切到云端，无需重构。
- 内置五信号循环检测（retry、oscillation、ping-pong、reflection、recall），能指出具体是哪些调用造成卡死，介入策略可选择性开启。
- 审计 v2 端点提供按 Agent 的哈希链（prev_hash → _this_hash）与 verify-chain 校验接口，便于做防篡改溯源。
- 记忆默认版本化，每次写入追加新版本，recall_history 可取回全部历史；另有共享记忆空间、冲突查询、快照与恢复。
- MCP 服务器提供 28 个工具，并有 LangChain、CrewAI、AutoGen、OpenAI Agents SDK 适配器，接入成本低。
- 本地语义搜索需要额外安装 octopoda[ai]（约 33 MB 嵌入模型）；未安装时 recall_similar 在本地返回 0 条结果并记录警告，行为与云端不一致。
- MCP 额外组件要求 Python 3.10+，核心包虽支持 3.9，但 3.9 用户无法使用 MCP 接入。
- 许可证在仓库元数据中标为 NOASSERTION，而 README 与徽章声明 MIT，采用前建议核实实际许可条款。
- 云端集成依赖 api.octopodas.com 与 octopodas.com 提供的密钥服务，免费档有 5 个 Agent、5,000 条记忆、60 rpm 的配额限制。
- MCP 客户端会重复服务器名前缀（octopoda_remember 暴露为 octopoda_octopoda_remember），修改注册环境变量后必须重启 Claude Code 窗口，仅重连 /mcp 不生效。
这个 Agent 与同类方案有什么区别？
README 给出了与 Mem0、Zep、LangChain Memory 的对比表：Mem0（Apache 2.0）与 Zep（部分社区版）偏云端优先，LangChain Memory 在进程内且需自备向量库；Octopoda 本地优先（SQLite），并额外提供循环检测、Agent 消息、哈希链审计、崩溃恢复、共享记忆、28 工具的 MCP 服务器，以及 LangChain、CrewAI、AutoGen、OpenAI Agents SDK 集成，语义搜索可本地或云端进行。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| Octopoda 当前 | 43 · 缺口较多 | ★ 486 | 2 个月前 | Python | Claude Code · Claude.ai · OpenAI API |
| Asqav SDK（Python + TypeScript） | 72 · 存在缺口 | ★ 507 | 11 天前 | Python | — |
| Caura | 70 · 存在缺口 | ★ 533 | 今天 | Python | Codex · Claude Code · Claude.ai |
| Ori Mnemos | 80 · 表现良好 | ★ 324 | 3 天前 | TypeScript | Claude Code · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
信任维度整体偏薄。最小权限：README 与 pyproject 未说明 SDK 运行时所需权限范围，仅能推断为本地 SQLite 与可选云 API 调用，未见权限声明或沙箱约束，扣分。用户确认：loop 检测的自动干预（auto-pause、spend cap）明确为 opt-in，但记忆写入、共享空间写入、审计写入均默认自动执行，无逐次确认机制，扣分。数据流透明：README 说明本地 SQLite 路径与云同步开关，但未给出数据出境/上传字段清单，扣分。敏感数据：SECURITY.md 列出 PBKDF2、SHA-256、RLS、TLS 等云端措施，但仓库内 SDK 侧未见对记忆内容的加密或脱敏处理，扣分。依赖安全：pyproject 仅给出下限版本（requests>=2.28.0、pydantic>=2.0.0 等），无锁文件、无哈希校验、无已知漏洞扫描配置，扣分。外部影响：CLI 会启动本地服务、写 ~/.synrix 与 ~/.octopoda 配置，属可预期副作用，但未在文档中集中声明全部写入位置，扣分。回滚：提供 snapshot/restore、forget、版本化记忆与 export/import，回滚路径相对完整，给 2 分。来源归属：LICENSE 明确 SDK 为 MIT、原生引擎为专有，但 README 徽章标注 MIT 与 LICENSE 中“SDK Code Only”存在口径差异，且发布者身份未验证，扣分。
自一致性：README 中包名混用 octopoda 与 synrix/synrix_runtime，数据目录同时出现 ~/.synrix/data 与 OCTOPODA_DATA_DIR，MCP 工具名存在双重前缀说明，说明命名与配置存在历史包袱，扣分。依赖可用性：核心依赖仅 requests 与 pydantic，可选 extras 分层清晰并标注 Python 版本差异（mcp 需 3.10+），可用性尚可，给 2 分。失败信息：README 提到 recall_similar 在本地无 AI extra 时返回 0 结果并记录警告，但未见统一的错误码或失败语义文档，扣分。
受众与场景：README 面向开发者，覆盖本地、云、MCP、多框架集成，场景描述充分，给 2 分。能力边界：宣称“自动检测框架并注入召回”，但未说明检测失败、非支持框架或超时时的降级行为，扣分。触发精度：loop 检测列出五类信号，但未给出阈值、误报率或调参方式，扣分。环境适配：明确 Python 3.9+、macOS CI 排除原因、Windows/Ubuntu 覆盖，环境说明较具体，给 2 分。
信息架构：README 目录完整、分节清晰，给 2 分。安装说明：pip extras 分层、Python 版本差异、本地模式哨兵值、MCP 注册更新注意事项均有说明，给 2 分。命名稳定性：octopoda 与 synrix_runtime 双命名空间并存，CLI 入口混用两套模块，稳定性存疑，扣分。示例与 FAQ：示例丰富，含 LangChain/CrewAI/AutoGen/OpenAI Agents SDK 与 MCP 配置，给 2 分。已知限制：仅零散提及 macOS CI 超时与本地语义搜索限制，无集中限制章节，扣分。许可证：LICENSE 为 MIT 但限定“SDK Code Only”，原生引擎专有，与 README 徽章及 pyproject license 字段的 MIT 表述不完全一致，扣分。版本与变更：pyproject 版本 3.3.5，CI 有 PyPI 版本一致性检查，但仓库内未见 CHANGELOG 文件内容，扣分。维护责任：SECURITY.md 给出邮箱与响应时限，但发布者身份未验证，维护主体不明确，扣分。
输出可用性：记忆读写、审计、快照、导出等 API 示例可直接使用，输出形态明确，给 2 分。边际价值：记忆与可观测层已有 Mem0、Zep 等成熟替代，README 对比表为自述且未提供独立基准，差异化证据不足，扣分。成本收益：本地零基础设施是优势，但云定价与专有原生引擎的许可边界可能带来额外成本与合规负担，扣分。
主张可追溯：README 大量性能与能力主张（十秒内出现、五信号引擎、28 个工具）未附可复现证据或基准数据，扣分。跨源印证：CI 工作流与 tests/ci_smoke.py 可部分印证快速开始与仪表盘启动路径，但云端与审计链主张仅由 README 自述，扣分。事实与推断分离：文档未明确区分已验证事实与营销表述，扣分。
- 发布者身份未经验证，README 徽章标注 MIT 而 LICENSE 限定为“SDK Code Only”，原生引擎为专有组件，商用前须核实许可边界。
- 记忆写入、共享空间写入与审计写入默认自动执行，loop 干预虽为 opt-in，但整体缺少逐次用户确认机制。
- 依赖仅设下限版本且无锁文件或漏洞扫描，供应链风险需自行评估。
- README 中 octopoda 与 synrix/synrix_runtime 命名混用，配置变量与数据目录存在两套口径，集成时需以实际代码为准。
- 大量能力与性能主张缺少可复现证据，云端与哈希链完整性主张仅由文档自述。