chromadb-memory

核心用法

chromadb-memory 是一款面向 OpenClaw Agent 生态的长期记忆插件，通过 ChromaDB 向量数据库与 Ollama 本地嵌入模型实现完全离线的语义记忆系统。其核心工作流程为：用户每次发送消息时，插件自动调用 Ollama（默认 nomic-embed-text 模型）将消息编码为 768 维向量，随后查询本地 ChromaDB 获取相似度高于阈值（默认 0.5）的历史记忆，并以 <chromadb-memories>> 标签形式注入当前对话上下文。此外，插件还提供 chromadb_search 工具供手动检索使用。

部署需预先启动 ChromaDB 服务（推荐 Docker）与 Ollama 嵌入模型，配置 collectionId 等参数后即可启用。关键配置项包括：autoRecall 开关、召回结果数量（默认 3 条）、相似度阈值 minScore，以及各服务端点地址。

显著优点

隐私优先的架构设计：100% 本地运行，零云 API 依赖，用户数据完全留存于自有硬件，彻底规避第三方服务的数据泄露风险。对于金融、医疗、法律等敏感场景尤为关键。

无缝的自动召回机制：无需用户手动触发，每轮对话自动完成嵌入、检索、注入全流程，大幅降低记忆管理的心智负担。Token 开销可控（最坏情况约 275 tokens），在 200K+ 上下文窗口下几乎无感知。

高度可调的检索策略：通过 minScore 与 autoRecallResults 参数灵活平衡召回精度与覆盖度，既支持高阈值精准匹配，也支持放宽条件获取更广泛关联信息。

清晰的生态定位：作为 OpenClaw 官方插件生态组成部分，与框架深度集成，配置规范统一，维护路径明确。

潜在缺点与局限性

基础设施依赖较重：需独立维护 ChromaDB 与 Ollama 两个本地服务，对非技术用户存在部署门槛；容器化方案虽简化操作，但仍要求 Docker 环境支持。

记忆质量依赖前置索引：插件本身不提供文档索引功能，用户需自行使用 ChromaDB 兼容工具完成数据入库，形成完整记忆闭环需额外工程投入。

召回效果受限于嵌入模型：默认 nomic-embed-text 虽为优质开源模型，但在特定垂直领域（如专业术语密集场景）的语义理解能力可能不及商业大模型嵌入服务。

无内置访问控制：若 ChromaDB 实例暴露于网络且未配置独立认证，存在潜在的数据越权访问风险，需用户自行加固网络隔离。

适合的目标群体

• 隐私敏感型用户：企业内网部署、涉密数据处理、个人知识库管理等对数据主权有严格要求的场景。
• 技术型开发者与运维人员：具备 Docker 与本地服务运维能力，追求架构可控性与成本优化的工程团队。
• 长期对话场景需求方：客服机器人、个人 AI 助手、研究辅助工具等需要跨会话维持上下文连贯性的应用。
• 开源生态拥抱者：偏好完全开源栈、希望避免 vendor lock-in 的独立开发者与组织。

使用风险

SSRF 配置风险：chromaUrl 与 ollamaUrl 参数接受任意 URL，若配置不当可能指向非预期服务，建议配合网络策略限制可访问端点。

服务可用性依赖：ChromaDB 或 Ollama 服务中断将直接导致记忆功能失效，需建立服务健康监控与故障降级机制。

召回噪声与信息过载：minScore 设置过低可能注入大量低相关记忆，干扰 Agent 判断；设置过高则可能导致关键上下文遗漏，需根据实际数据分布反复调优。

Token 预算累积：虽单次开销微小，但高频长对话场景下自动召回的累积 Token 消耗仍需纳入上下文窗口规划。

版本兼容性：ChromaDB 与 Ollama 的 API 演进可能引入破坏性变更，升级依赖服务前需验证插件兼容性。