zer0dex 本地双层记忆
用可读索引与本地语义检索，为长期运行的智能体保留跨会话记忆。
按维度查看评分与理由
项目采用本地 Ollama、Chroma 和项目级存储，主机必须显式调用查询；后台服务停止前还会核验启动令牌和进程身份，发布流程只授予读取内容及 PyPI OIDC 所需权限。数据流、文件位置、外部效果及第三方组件披露充分，作者和 Hermes Labs 归属也清楚。扣分在于未提供服务器鉴权、加密、秘密扫描或依赖漏洞审计证据；项目明确不是访问控制或隐私治理系统。依赖仅设最低版本而无上限或锁文件。停止服务和清理失效状态有恢复措施，但未展示记忆删除、备份或数据写入回滚机制。
README、包元数据、CLI 命令和测试呈现一致的产品模型；另有测试核对多个版本声明，并覆盖配置往返、参数校验、服务就绪、端口冲突、失效状态、进程身份和本地 HTTP 交换。错误路径通常非零退出且给出具体提示，包括 Ollama 不可达、客户端缺失和未提取到记忆。扣分主要来自运行依赖仍要求外部安装并运行 Ollama及下载两个模型，依赖使用宽松最低版本，且所给材料不含完整实现，无法静态确认所有兼容路径。
目标用户、适用场景、双层架构、主机集成责任和非目标均有明确说明；查询触发点被限定为主机在模型调用前显式执行，示例适配器还要求将检索结果置于不受信任上下文，避免隐式注入。支持自定义集合、端口、存储路径、用户和模型配置。扣分在于经 CI 覆盖的环境仅为 Python 3.11/3.12 和 Ubuntu，后续 Python 版本及其他操作系统虽在元数据中宣称可用，但没有相同程度的材料支持。
README 信息层次清晰，包含快速预览、受众、原理、安装、首次成功、集成、证据限制、非目标、开发、引用和许可；命令示例完整，名称及版本由测试跨 pyproject、运行时、引文和机器可读文档核对。Apache-2.0 全文存在，Alpha 状态、安全联系渠道、支持版本和响应目标也有说明。扣分在于没有独立 FAQ；变更日志和兼容性政策仅被引用而未包含在给定证据中；维护责任有作者、组织和安全邮箱，但发布者身份未经企业注册表验证，且未展示更广泛的维护团队或长期接替安排。
查询输出为简洁、可注入的结构化记忆列表，含文本、相关性分数和来源；双层设计相较纯平面文件或纯向量检索具有清晰的可检查性和跨项目检索增益。README 报告单一 86 条记忆、97 个案例工作负载上的召回结果，并主动限制其外推范围。扣分在于评估正文未包含在材料中，增益只由 README 摘述；资源需求仅定性说明需要模型、内存和磁盘，没有量化安装体积、延迟或持续运行成本，因此成本收益仍需用户在代表性数据上验证。
多数操作性主张可追溯到包元数据、CI 配置和具体测试；版本、命令、进程安全、错误行为及本地交互在多个文件之间相互印证。示例明确标注为 illustrative，性能数字明确区分工作负载证据与一般保证，事实和推断分离良好。扣分在于完整实现、评估 README、兼容性文件和变更日志未提供，故性能主张及部分文档承诺不能由当前材料交叉核验。
- 本工具不是访问控制、隐私、合规或治理系统；不要把敏感记忆放入未加密或权限不明的项目目录。
- 检索内容被明确视为不受信任数据；主机应在注入提示前执行来源、权限和提示注入检查。
- 依赖未锁定且未展示漏洞扫描；生产使用前应锁定并审计 mem0ai、ChromaDB、Ollama 客户端及 CI Actions。
- 91.2% 平均召回和 80.0% 交叉引用召回仅来自一个小型单次工作负载；应使用代表性数据重新评估阈值、延迟和资源成本。
- 服务停止有身份核验，但材料未展示记忆删除、备份、迁移或写入回滚流程；上线前需制定数据恢复方案。
这个 Agent 能做什么，适合哪些场景？
zer0dex 是一个面向智能体宿主的本地双层记忆参考实现，由人工可编辑的 Markdown 索引与基于 mem0、Chroma 的语义记忆库组成。宿主将精简索引保留在上下文中，并在每次模型调用前通过本地 HTTP 服务检索与当前消息相关的记忆。项目提供 Python CLI、本地服务器以及 POST /query、POST /add 和 GET /health 接口，但不会自动安装调用前钩子，也不是完整的智能体框架。默认方案通过 Ollama 在本机运行 nomic-embed-text 和 mistral:7b，不需要托管记忆服务或云端 API 密钥。查询返回包含文本、相关度分数和来源的 memories，具体如何验证并注入模型提示词由宿主负责。项目仍处于 0.1.x Alpha 开发预览阶段，更适合能自行完成集成并接受接口继续调整的开发团队。
用户创建或编辑 MEMORY.md，把分类、长期摘要和跨主题指针放入可读索引；zer0dex seed --source MEMORY.md 将内容写入项目本地的 mem0/Chroma 存储。zer0dex serve --background 启动本地 HTTP 服务，并在配置的存储目录中记录 server.json 进程状态。智能体宿主在每次模型调用前向 POST /query 发送当前问题，服务执行语义检索并返回 memories；每条结果可包含 text、score 和 source。POST /add 或 zer0dex add 可提取并保存新记忆；如果没有存入任何记忆，命令会以非零状态退出。GET /health、zer0dex check 和 zer0dex status 用于检查运行状态，zer0dex stop 会在验证每次启动的进程身份后停止托管服务器。仓库中的 queryZer0dex TypeScript 示例展示了有界、失败时放行的调用方式，并建议把检索结果置于明确标记为不可信的上下文字段。
- 在本机运行编码或研究智能体的开发者，希望项目事实在不同会话之间持续存在，同时仍能直接检查和编辑核心记忆。
- 已经发现单个 MEMORY.md 过大、无法全部放进提示词的团队，希望保留简洁目录，并按当前问题语义检索细节。
- 不愿只依赖不透明向量库的智能体框架作者，需要用 Markdown 展示知识分类、稳定摘要和主题间关系。
- 能够在模型调用前增加一次本地 HTTP 请求的宿主开发者，希望自行控制哪些检索结果进入提示词。
- 需要跨项目回忆但不能使用托管记忆服务或云端 API 密钥的本地优先工作流。
- 准备在自己的数据上评估记忆召回效果的可靠性团队，可借鉴仓库提供的双层架构和评测方法。
这个 Agent 有哪些优点和局限？
- Markdown 层可由人直接审阅和编辑，同时保留 Chroma 语义检索细节，兼顾可见性与按需召回。
- 默认完全本地运行，Ollama、mem0 和 Chroma 方案不要求托管记忆服务或云端 API 密钥。
- CLI 与小型 HTTP 接口边界清晰，可接入不同宿主，而不强制采用完整智能体框架。
- 后台停止逻辑会验证每次启动的进程身份，避免陈旧或复用的 PID 误伤无关进程。
- 项目明确提供评测方法和局限说明；所述 86 条记忆、97 个案例工作负载中，平均召回率为 91.2%，跨引用召回率为 80.0%。
- 宿主必须自行实现模型调用前的查询、结果筛选、信任边界和提示词注入；项目不提供自动钩子安装。
- 默认运行依赖 Ollama、nomic-embed-text、mistral:7b、mem0ai 和 ChromaDB，并需要相应的本地内存与磁盘。
- 项目仍是 0.1.x Alpha 开发预览；尽管文档称破坏性变更前会提供迁移说明，接口仍可能继续调整。
- 现有评测只有一个由 86 条记忆生成的 97 案例工作负载、单次评分且没有置信区间，不能证明跨领域或数千条记忆时的表现。
- 它不提供多租户托管、合规、访问控制、隐私治理，也不保证检索到的文本真实、安全或适合注入。
如何安装或部署这个 Agent？
需要 Python 3.11 或 3.12，以及已安装并在 http://localhost:11434 提供服务的 Ollama。创建环境并安装：
python -m venv .venv
source .venv/bin/activate
pip install zer0dex
zer0dex --version下载所需本地模型：
ollama pull nomic-embed-text
ollama pull mistral:7b安装包会同时带入 mem0ai、ChromaDB 和 Ollama Python 客户端；默认流程不需要云端 API 密钥。还需预留足够的本地内存和磁盘空间容纳模型及 Chroma 存储。
如何使用这个 Agent？
可复制的首次运行流程：
printf '%s\n' '# Memory' '## Project Atlas' '- Deployment target: staging' > MEMORY.md
zer0dex check
zer0dex init
zer0dex seed --source MEMORY.md
zer0dex serve --background
zer0dex query "Where does Project Atlas deploy?"
zer0dex add "Project Atlas deploys from the release branch"
zer0dex status
zer0dex stop初始化会在当前工作目录创建 .zer0dex.json 和本地 .zer0dex/ 存储。正式接入时，在每次模型调用前请求 POST /query，并按照自己的提示词和信任策略处理返回的 memories。也可使用 POST /add 写入记忆、GET /health 检查服务。TypeScript 宿主可参考仓库的 queryZer0dex 适配器，但仍需把该辅助函数接入自己的消息流水线。
这个 Agent 与同类方案有什么区别？
与不断扩大的单一 MEMORY.md 相比，zer0dex 只让精简的语义目录常驻上下文，把详细信息交给按需检索，因此更适合无法把全部记忆塞进提示词的场景。与纯向量存储式 RAG 相比，它增加了可人工检查和编辑的 Markdown 层，用来呈现已有知识、分类和跨主题关系；代价是必须同时维护索引与本地向量存储，并由宿主完成两者的使用策略。