mnemostack 是一个自托管的混合记忆与检索层，构建在用户自己的 Qdrant 向量数据库之上，并可选使用 Memgraph 图数据库。它面向 AI 应用和智能体，提供持久化、可搜索、可解释的记忆能力。
用途
mnemostack 的核心用途是为 AI 智能体提供持久化记忆。长时间运行的智能体常遇到上下文被压缩、会话重启后有用决策丢失、下一次运行需要重新熟悉环境的问题。mnemostack 提供一个持久记忆层，当上下文窗口不足时，智能体可以通过一次 recall(query) 调用从存储中拉取精确事实。
同一引擎也适用于其他检索密集型工作：混合语料上的 RAG、多租户或按用户隔离的知识库、时间感知搜索后端等，尤其适合纯向量相似度不够用的场景。
主要能力
- 混合检索：向量检索、BM25 关键词检索、时间检索和图检索并行运行，通过 Reciprocal Rank Fusion 融合排序。
- 8 阶段排序管线：可进行查询分类、精确 token 救援、重力/枢纽抑制、新鲜度混合、返回抑制、好奇心提升、Q-learning 权重和图复活等处理。
- 可选 LLM 重排序与答案合成：在召回结果之上进行最终排序，或生成带置信度和引用的答案；LLM 不可用时检索仍可工作。
- 多租户隔离：通过 payload 过滤器在每个检索器中隔离租户数据，或启用服务密钥认证（serve --auth）实现硬性租户边界，并可选按租户配额。
- 数据摄入与结构化投影：摄入路径可丰富并投影结构化字段，支持流式 Ingestor API 实时存储消息。
- 反馈循环：通过 HTTP 或 MCP 的 /feedback 显式更新有用性信号，不会静默训练每个响应。
- 优雅降级：任一检索器失败时记录日志并继续使用剩余来源；降级状态通过 degraded 标签可见，完整追踪可通过 include_trace 按需获取。
使用方式
mnemostack 提供三种使用方式：
- MCP 服务器：适合智能体用户。运行 mnemostack mcp-serve，连接 Claude Desktop、Claude Code、Cursor、ChatGPT 等支持 MCP 的智能体，即可使用记忆工具（如 mnemostack_search、mnemostack_answer 和图工具）。
- HTTP API：适合应用开发者。运行 mnemostack serve，从任意语言调用 /recall、/answer、/feedback、/memories、/invalidate、/triples、/health、/metrics、/docs 等端点。
- Python SDK：适合库用户。在自己的 Python 应用中组合检索器、存储、重排序器、图工具和流式摄入 API。
快速开始需要先运行本地 Qdrant 作为向量存储，可选运行 Memgraph 支持图记忆。索引文件夹中的笔记、文档、转录或项目上下文时，--recreate 会先请求确认，脚本或 CI 中需加 --yes 跳过提示。
适用场景
- 长时间运行的编码智能体，需要跨压缩和会话重启保持记忆。
- 聊天助手和对话机器人，跨会话记住用户消息、偏好和决策，并通过 payload 过滤器隔离每个用户的记忆。
- 个人助理记忆，用于偏好、重复任务和长期上下文。
- 多智能体通过一个持久记忆后端共享上下文。
- 会话压缩恢复，当有用细节不再适合放入提示时。
- 可搜索知识库：摄入文档、笔记、FAQ 后，通过 CLI、HTTP 或库提供混合搜索或带引用的 answer()。
- 混合语料（代码、文档、转录）上的 RAG，精确 token 和时间召回优于纯向量相似度。
- 多租户或按用户的知识存储。
- 时间感知搜索和知识库，如“上周发生了什么变化”、时间点图事实、新鲜度加权排序。
- 团队或项目知识召回，覆盖文档、笔记、工单和聊天历史。
限制与说明
- 需要自托管 Qdrant，图功能需要可选运行 Memgraph。
- 召回结果列表的顺序是权威的，score 没有统一尺度，不应重新排序或跨查询比较。
- 查询扩展在检索前运行，配置错误会直接报错而非静默降级。
- 多进程服务器需要自行实现 StateStore（get、set、update 三个方法），可基于 Redis 或数据库。
- 基准测试结果依赖数据集版本、配置、评判模型、评分规则和查询类型，外部报告的数字仅供参考。
- 项目处于活跃开发中，公共 API 稳定，新功能以增量方式加入次要版本，破坏性变更较少并在 CHANGELOG.md 中说明。
