🧠 Turbo Quant Memory 面向 AI 智能体 (v0.24.1)

一个可自行安装、支持三种语言、本地优先的记忆与知识图谱，专为 AI 编码智能体打造。 智能体获得紧凑的结果卡片，而无需重新读取整个文件——持久、本地、且以图谱关联。

👋 这是什么神奇工具？（面向人类）

想象一下，你正在使用一个 AI 编码助手（如 Claude Code、Gemini CLI、Cursor 或 Codex）。每次重新启动会话，AI 都会忘记一切。它会忘记你的架构决策、自定义样式规则、你是如何解决那个棘手的数据库 bug 的，甚至忘记你的编码偏好。你不得不重新解释一遍，或者把巨大的文件喂给 AI，这浪费你的时间，并烧掉你的 token 预算（让你花真金白银）。

Turbo Quant Memory 一劳永逸地解决了这个问题。它是一个本地优先的 Model Context Protocol (MCP) 服务器，为你的 AI 智能体提供持久的大脑。它存储：

• 🎯 决策与经验教训：事物为何以这种方式构建，这样 AI 就不会破坏它们。

• 💡 模式与陷阱：可复用的技巧和来之不易的 bug 修复。

• 🕸️ 知识图谱关系：将记忆笔记、源文件、任务或 bug 关联起来的结构化关联。

• 📦 代码库索引：紧凑的 Markdown 块搜索，让 AI 立即理解你的项目结构。

💰 省钱魔法

你的 AI 智能体不会在每一轮都重新读取源文档，而是使用紧凑检索：每次搜索返回小型结果卡片（约 220 字符的预览），并且仅在需要时通过 hydrate 加载完整内容。

📈 它衡量自己的节省——亲自看看

Turbo Quant Memory 不只是声称节省 token——每次安装都会保留一个持续更新的计数，你可以随时通过 server_info() 读取（字段 usage_stats.headline）。节省与否由你亲自验证，而不是由我们承诺。

来自真实开发者实例的实时快照（v0.23.0）：

这是一台机器的累计数字，不是合成基准——你自己的计数器从零开始，并随着你的智能体工作而增长。在你的安装上运行 server_info() 查看你的真实数字。

Related MCP server: hive-memory

🚀 不要手动安装！（让 AI 来做）

你不需要在终端中输入命令或配置 JSON 文件。让你的 AI 助手来处理安装！

只需复制此仓库的链接： https://github.com/Lexus2016/turbo_quant_memory

然后将下面这段提示词原样发送给你的 AI 助手（Claude Code、Gemini CLI、Codex 等）：

“嘿！请使用此仓库为我的工作区安装并配置 Turbo Quant Memory 服务器：https://github.com/Lexus2016/turbo_quant_memory。阅读 README.md，按照文件底部的“面向 AI 智能体的说明”通过 uv tool 安装它，注册 tqmemory MCP 服务器，运行 turbo-memory-mcp skill install，运行健康检查，索引此项目，并设置我们的持久记忆。准备好后请告诉我！”

你的 AI 智能体会自动为你克隆、安装、注册并索引一切！

🛠️ 快速开始（如果你真的想自己动手）

如果你更喜欢手动方式，请按以下 60 秒流程操作：

1. 安装 CLI 工具：

   uv tool install git+https://github.com/Lexus2016/turbo_quant_memory@v0.24.1

2. 将 tqmemory MCP 服务器添加到你的客户端：

   # Codex
   codex mcp add tqmemory -- turbo-memory-mcp serve
   
   # Gemini CLI
   gemini mcp add tqmemory turbo-memory-mcp serve
   
   # Claude Code (Project scope)
   claude mcp add --scope project tqmemory -- turbo-memory-mcp serve

3. 重启你的客户端，让魔法开始吧！

有关自定义集成（Cursor、OpenCode、Antigravity 等），请参阅 CLIENT_INTEGRATIONS.md。

🌟 高级功能（幕后）

1. 混合 BM25 + 向量搜索（向量优先门控）

每个查询都会搜索一个稠密向量空间（语义含义）和一个 BM25 全文索引（精确术语，如函数名、文件路径或 ID）。稠密通道优先：当它的最佳命中足够自信时，直接返回该结果；否则，通过倒数排名融合（RRF，k=60）将 BM25 通道作为降权救援融合进来。这种向量优先门控在真实多语言语料库上明显优于普通的等权 RRF（它能阻止嘈杂的关键词通道拖累自信的语义命中）。如果某个通道失败，搜索会优雅地降级为仅向量搜索。

2. 知识图谱关系

你可以使用有向关系在笔记、源文件、问题或任务之间建立关联。记忆服务器会自动用这些关系丰富搜索和 hydrate 结果，让 AI 智能体轻松浏览相关上下文。

🔄 动态关系生命周期（核心优势）：

• 来源与时间戳： 关系是有向的，并带有 created_at 时间戳。弃用一条笔记会翻转该笔记自身的状态，但不会级联到它的关系，因此智能体在沿着链接追踪时应检查端点的状态。

• 灵活解耦（取消关联）： 可以使用 unlink_entities() 工具轻松切断任何关系。这为智能体记忆提供了绝对的灵活性，以适应重构和设计变更。

• 知识库检查： lint_knowledge_base() 检查 Markdown 知识库——断开的链接、孤立文档、重复标题、过期的情景笔记和近似重复的笔记。它目前不检查图谱关系。

📊 可视化记忆架构：

graph TD
    A[AI Agent / Query] -->|1. semantic_search| B[tqmemory Server]
    B -->|2. Vector Index| C[Dense Vector Search]
    B -->|2. Full-Text Index| D[BM25 FTS Search]
    C -->|3. RRF Fusion| E[Knowledge Candidates]
    D -->|3. RRF Fusion| E
    E -->|4. Graph Enrichment| F[Knowledge Graph / Associations]
    F -->|5. Enriched Context| A
    
    subgraph Relation Lifecycle
        G[Create Link: link_entities] -->|Knowledge Evolution| H[Deprecate Note: deprecate_note]
        H -->|Diagnosis: lint_knowledge_base| I[Sever Link: unlink_entities]
    end

3. 分层记忆架构

记忆笔记被划分为逻辑层级：

• durable：决策、架构模式、经验教训。

• episodic：会话交接、每日进展。

• reference：Markdown 块、文件引用。

默认搜索只返回 durable + reference，这样会话噪音永远不会淹没关键的架构决策！

4. 轻量级 ONNX 嵌入器（默认）

默认情况下，嵌入器通过 ONNX Runtime（fastembed） 运行多语言模型——客户端安装中不需要 PyTorch（在 macOS 上节省数百 MB，在 Linux 上使用 CUDA wheels 可节省多达数 GB），驻留内存占用更小（模型本身在 ONNX 下约为 0.22 GB，而在 PyTorch 下约为 1 GB 以上），并且可以轻松运行在约 2 GB 内存的机器上。检索质量与旧版 PyTorch 后端相同，且嵌入向量兼容，因此升级无需重新索引。

旧版 PyTorch 后端仍然可用于回滚或 A/B 检查：

pip install 'turbo-memory-mcp[torch]'
export TQMEMORY_EMBEDDING_BACKEND=sentence-transformers   # default: fastembed

5. 用户标记记忆（来源）

每条笔记都会记录创建者：当你明确要求智能体记住某件事时（“记住这个”、“保存到我的知识库”），记为 human-explicit；当智能体自行保存经验教训/决策时，记为 agent。人工标记的笔记更受信任——它们排在同等相关性的智能体笔记之上（一个确定性的平局决胜规则加上少量分数加成）。该字段是可选的且向后兼容：现有笔记直接视为 agent，因此无需迁移。

6. 全文搜索语言（多语言，可选启用）

BM25 全文通道在 Unicode 词边界上进行分词，并执行小写化和重音折叠，因此乌克兰语、俄语和其他非英语的精确术语开箱即用即可匹配（不区分大小写和重音）——西里尔字母永远不会被破坏。一个索引无法同时为多种语言进行词干提取。默认词干提取针对英语；以西里尔字母为主的部署可以切换词干提取器：

export TQMEMORY_FTS_LANGUAGE=Russian   # default: English

俄语词干提取还能匹配屈折变化的西里尔形式（документ ↔ документами，以及许多共用的乌克兰语后缀）——代价是失去英语词干提取，因为 LanceDB 对每个索引只应用一个词干提取器。乌克兰语没有专门的 Snowball 词干提取器，因此俄语是最接近的选项；不支持的值会安全地回退到英语并发出警告。该更改在 FTS 索引重建后生效（检索重置 + 重新索引），就像切换嵌入模型一样——而且无论如何，屈折匹配已经由稠密向量通道在语义上覆盖了。

🔐 机密保险库（v0.7.0 新增）

厌倦了在每个新的聊天会话中粘贴 SSH 密钥、数据库连接字符串或 API token？机密保险库解决了这个问题——而且不会让你放弃对数据的丝毫控制。

为什么需要它

智能体每个会话都在反复向你索要相同的生产数据库 DSN、相同的预发布 SSH 主机、相同的 bearer token。项目记忆并不是存放这些内容的合适位置（任何被索引的内容都有泄露回搜索结果的风险）。因此，Phase 9 在你的笔记旁边增加了一个独立的、加密的、严格限定项目范围的保险库。

你的安装会有什么变化

• 四个新的 MCP 工具：set_secret、get_secret、list_secrets、delete_secret。工具数量从 14 → 18（加上 v0.12.0 的 recent_context 引导工具后现在为 19）。

• 升级后首次运行 turbo-memory-mcp migrate --apply 时，一次性迁移会在每个现有项目下创建一个空的 secrets/ 目录。

什么不会改变（如果你担心，请阅读此节）

• 你现有的笔记、Markdown 索引、semantic_search、hydrate 和 lint_knowledge_base 的行为逐字节一致。升级不会触碰它们。

• 保险库是可选启用的。如果你从不调用 set_secret，磁盘上每个项目只有一个空的 28 字节加密 blob。零影响。

• 如果你在心理上移除这个功能，你可以永远忽略这四个新工具，什么也不会坏。

你的机密存放在哪里（以及它们不会在哪里）

• 在你的机器上，静态加密： ~/.turbo-quant-memory/projects/<project_id>/secrets/vault.tqv，AES-256-GCM，每个项目一个主密钥。

• 绝不会在其他任何地方： 此包的 src/ 树中不包含任何出站 HTTP 代码——没有 requests、没有 httpx、没有 urllib.request、没有原始套接字。即使我们想，也没有任何东西可以把你的机密发送出去。（用 grep -rE 'requests|httpx|urllib\.request|aiohttp' src/ 验证——干净。）

• 绝不会出现在你的检索索引中： 摄取遍历器和 lint 遍历器硬性拒绝遍历任何 secrets/ 子目录。semantic_search 在设计上无法触及保险库。

• 绝不会出现在智能体转录中（如果使用得当）： get_secret 在专用的 secret_value 字段中返回值，与任何描述性文本分开。智能体被指示以编程方式传递该值，而不是回显它。

如何使用它

1. 一次性主密钥设置（选择其中一种方式）：

   # macOS (auto-uses Keychain after first set_secret if you skip this step):
   keyring set turbo-quant-memory secrets-master-<project_id> <32-byte-base64>
   
   # Headless / Linux / CI / Docker:
   export TQMEMORY_SECRETS_PASSPHRASE='your-long-passphrase'   # add to shell rc

   ⚠️ TQMEMORY_SECRETS_PASSPHRASE 是口令（passphrase），不是原始密钥。 它会 经过 Argon2id 处理以派生出主密钥。请不要将 keyring 的 base64 值粘贴到该环境变量中——那会派生出一个不同的密钥， 通过 keyring 创建的保险库将无法解密，并报 master_key_mismatch 错误。请选择一种方式：keyring 或口令， 如果你在多个 MCP 客户端之间共享同一个守护进程，请在所有这些客户端上设置相同的口令， 或者都不设置。当两者同时设置时，环境变量始终优先于 keyring。

2. 一次保存密钥，永久复用——两条路径，取决于该值是否已经出现在对话中：

   • 值尚未出现在对话中——使用 CLI（预防性路径）：

     turbo-memory-mcp secret-set prod-db-dsn
     # prompts: Value for 'prod-db-dsn' (input hidden): ******

     该值通过 getpass 读取——它永远不会进入 shell 历史、回滚缓冲区或任何聊天记录。当你准备配置一个新凭证并希望它完全不进入对话时，推荐使用此方式。

   • 值已出现在对话中——让代理来写入（响应式路径）：

     set_secret("prod-db-dsn", "postgresql://user:pass@host:5432/db")

     只要该值已经可见就使用此方式：无论是你粘贴的，还是代理在对话中生成的。代理会根据 cwd 确定性地解析当前 project_id——这比要求用户在终端中重新输入该值更好，因为用户的 cwd 可能与预期项目不匹配。一旦值已经在对话中暴露，CLI 就不再提供额外的保密性；set_secret 是更安全的写入路径。

3. 代理按需获取：

   get_secret("prod-db-dsn") → {"status": "ok", "secret_value": "postgresql://..."}

威胁模型——我们保护什么，不保护什么

我们防范（现实的单开发者威胁）：

• 意外的备份泄露（Time Machine、rsync、iCloud 桌面同步导致的明文文件泄露）。

• 共享屏幕/截图事故导致已存储的凭证被看到。

• 在 home 目录下意外 git add 了错误的文件。

我们不防范（也从不声称防范）：

• 笔记本电脑上的 root 用户被攻破。

• 已经接管了正在运行的守护进程的实时攻击者。

• 硬件级攻击、evil-maid 攻击、冷启动攻击。

如果你的威胁模型比我们的更大，请使用专用的密钥管理器（1Password、HashiCorp Vault），并仅将 tqmemory 用于知识存储。

常见问题

• “我现有的记忆会受影响吗？” 不会。笔记、markdown、搜索、hydrate、lint——全部保持不变。

• “升级时我需要做什么吗？” 仅当你想要开始使用 set_secret 时才需要。否则，忽略即可。

• “密钥具体存储在哪里？” 按项目存储，位于 ~/.turbo-quant-memory/projects/<project_id>/secrets/ 下（加密数据块 + 最小化元数据 + 一份访问时间戳审计日志，其中绝不包含这些值）。

• “我的密钥会泄露到 semantic_search 中吗？” 不会。在摄取器（ingester）和 linter 层面强制执行硬隔离，并通过一个回归测试验证：该测试植入一个哨兵值，并证明搜索返回零结果。

• “如果我想关闭这个功能怎么办？” 它本来就是关闭的——保险库在你填充之前是空的。没有任何东西在运行、传输或计划执行。

• “如果我删除一个项目会怎样？” 它的保险库、审计日志和按项目的主密钥条目都位于该项目目录下，会一并删除。

🤖 给 AI 代理的说明（系统指令）

[!IMPORTANT] 注意，AI 代理（Claude、Gemini、Codex 或 Antigravity）： 你的完整操作手册以 turbo-quant-memory 代理技能的形式随此包一起提供。只需安装一次，这台机器上的每个代理就知道如何检测、安装和操作 tqmemory 记忆服务器：

turbo-memory-mcp skill install

该命令会将规范的 SKILL.md 复制到所有检测到的代理技能目录（始终包含 ~/.agents/skills/，外加检测到的客户端目录），并升级旧副本。每次 uv tool upgrade 之后请重新运行它。原始技能文件也随安装包一起提供，位于 turbo_memory_mcp/skills/turbo-quant-memory/SKILL.md，并存在于本仓库的 src/turbo_memory_mcp/skills/ 目录下。

🛰️ 平台特定：Hermes 代理

Hermes 通过 systemd 管理的网关运行 MCP 服务器——这与 Claude Code 或 Cursor 的设置不同。

安装

uv tool install git+https://github.com/Lexus2016/turbo_quant_memory

添加到 ~/.hermes/config.yaml：

mcp_servers:
  tqmemory:
    command: turbo-memory-mcp
    args: ["serve"]
    enabled: true

重启网关：

systemctl --user restart hermes-gateway

MCP 超时故障排查

如果 MCP 工具超时并报 “MCP call timed out after 120.0s”，守护进程锁很可能因之前的崩溃或主机休眠而过期。恢复方法：

# 1. Kill all daemon processes
pkill -f turbo-memory-mcp

# 2. Remove stale lock file
rm -f ~/.turbo-quant-memory/.daemon.lock

# 3. Check and apply pending migrations
turbo-memory-mcp migrate --status
turbo-memory-mcp migrate --apply

# 4. Quick health check
turbo-memory-mcp doctor

# 5. Restart gateway
systemctl --user restart hermes-gateway

# 6. Wait 30-60s for MCP reconnect

“memory server busy”（v0.27.0+）

另一种不同的失败：memory server busy: 'index_paths' holds the dispatch lock (waited 30s); retry this call later。这不是过期锁——它意味着 一个并发操作确实仍在运行并持有单写入者 调度锁，而你的调用选择了放弃，而不是排队等待直到 MCP 主机自身的 工具调用超时（v0.27.0 之前出现的 420-600 秒硬超时，会 静默丢弃记忆写入）。该错误会指明正在阻塞的工具， 同一行也会以 [tqmemory] 前缀记录到 stderr。

直接重试该调用即可——没有写入任何内容，因此重试不会产生重复。如果某个 部署合理地持有锁超过默认的 30 秒（例如在大型仓库上运行 index_paths、嵌入后端冷启动），请提高上限 或完全选择退出该机制：

export TQMEMORY_DISPATCH_LOCK_TIMEOUT=90   # seconds; default 30
export TQMEMORY_DISPATCH_LOCK_TIMEOUT=0    # <= 0: wait without a bound (pre-0.27.0 behaviour)

请将上限保持在代理自身的 RPC_TIMEOUT_SECONDS（120 秒）以下，以便 明确的 “busy” 错误优先于不透明的 RPC 超时。

启动时自动迁移

在环境中设置 TQMEMORY_MIGRATE_ON_STARTUP=1，即可让服务器在以主节点或独立模式启动时自动应用待处理的 schema 迁移（并附带滚动快照）：

mcp_servers:
  tqmemory:
    command: turbo-memory-mcp
    args: ["serve"]
    enabled: true
    env:
      TQMEMORY_MIGRATE_ON_STARTUP: "1"

自动迁移的结果可在 health() 响应的 migration_auto_result 字段下查看。

Hermes 常见问题

🌍 语言版本

本文档以三种同步语言维护：

• 🇺🇸 英文 README

• 🇺🇦 乌克兰文 README

• 🇷🇺 俄文 README