rag-kb 是一个本地优先、完全离线可用的 Agent 记忆与知识服务，采用 REST + MCP 双协议，提供混合检索（向量 + BM25 归一化加权融合）、文档/网页入库与 RAG 问答；在无 LLM 时存取与检索仍完整可用。仓库包含两个子系统（kb 与 agent-orchestra），开源协议为 Apache-2.0（含专利授权，可商用）。
用途方面，kb 面向 Claude Code / Cursor / TraeWork / 自建 Agent，提供记忆写入、文档与网页入库、混合检索与 RAG 问答，并以 Windows 单进程常驻方式运行（python -m kb serve）。
主要能力包括：单进程常驻，一个 python -m kb serve 同时提供 REST API 与 MCP 端点；混合检索，BGE-M3 向量检索 + BM25 关键词检索，每路 min-max 归一化后按生效路数均权融合排序，中文分词友好；可选精排，设置 KB_RERANK_ENABLED=true 启用 bge-reranker-v2-m3 交叉重排（默认关）；可选三路，设置 KB_SPARSE_ENABLED=true 启用 BGE-M3 稀疏向量第三路（默认关，失败自动降级双路）；记忆管理，支持写入/更新/删除/列表，支持 namespace、tags、type 过滤；记忆全共享（v3），本地单用户定位，所有记忆/知识与任何客户端、任务、AI 全共享，client/project 仅用于审计归类与元数据，主键服务端生成；存取审计，每次写/读/改/删/检索/问答记 JSON 到 logs/agent-audit/<客户端>__<项目>.log，可通过 REST GET /api/v1/audit?client=<客户端>[&project=<项目>] 或 CLI kb audit --client <客户端> 查询；知识入库，支持本地文档（txt/md/pdf/docx 等）上传或路径导入，以及网页正文抓取入库；目录监听，通过 KB_WATCH_DIR 指定目录内新增/删除文件自动入库/清理；CLI 工具，kb add/search/stats/ask/eval/forget/dedup；隐私护栏，敏感 namespace 强制本地回答不出网，/ask 智能路由本地优先、难题可选云端；断网可用，模型与数据全部落本地。
使用方式上，安装需在 Windows / Linux / macOS 上创建虚拟环境后安装依赖；kb 命令只装在虚拟环境内，每个新终端都要先激活虚拟环境（Windows 使用 .\venv\Scripts\Activate.ps1，Linux/macOS 使用 source venv/bin/activate），否则会提示 kb 未找到命令，改用 python -m kb <子命令> 可绕过激活。备选方案为免虚拟环境安装（Python 3.10+）：pip install --user -r requirements.txt 后用 python -m kb serve 运行，但建议优先使用 venv 隔离依赖。首次启动会加载本地嵌入模型（默认 BAAI/bge-m3，约 2GB，需提前下载缓存）；未配置 LLM 时服务照常启动，/ask 返回 503 与配置指引。LLM 默认关闭（KB_LLM_MODE=off），服务启动不会探测/加载/调用任何大模型，零显存、零成本、纯离线。需要 RAG 问答时，可配置本地 LLM（Ollama）或云端 LLM（任意 OpenAI 兼容服务商，不绑定 DeepSeek，DeepSeek / OpenAI / 通义千问 / 硅基流动 / Moonshot 等均可，通用三键）。验证方式为 GET /api/v1/healthz 的 llm 字段：local / cloud 表示已就绪，disabled 表示未启用。中国大陆直连 huggingface.co 会超时，可设置 HF 镜像后重启：export HF_ENDPOINT=https://hf-mirror.com，或写入 ~/.bashrc 永久生效；模型会自动从镜像下载并缓存到 ~/.cache/huggingface/hub/，之后断网也能离线加载。模型已在本机缓存但无外网时，kb 采用离线优先（先命中本地缓存，失败才联网），只要缓存目录完整即可完全离线运行。
Agent 接入方式为客户端无关：推荐安装 skill（仓库内 skills/kb-memory/SKILL.md 是客户端无关的 Anthropic 开格式 skill，复制到所用客户端的用户级 skills 目录后，该客户端的任何项目会话都会在读写记忆/RAG 问答/审计查询时自动识别并触发；安装即复制目录，有脚本也可手动复制，无需依赖；更新、卸载及使用说明见 scripts/README.md）；不装也不影响 kb 服务，可用纯文本提示词兜底：整段复制 docs/AGENT_PROMPT.md 粘贴给 Agent 即可，任何客户端通用。需要注意，.trae-cn/skills、.claude/skills、.cursor/skills 并非统一标准目录，只是各家客户端的用户级约定目录，SKILL.md 本身是统一的 Anthropic 开格式，但装到哪个目录、能否自动触发由各客户端自行决定，支持程度不一。
MCP 端点（streamable HTTP）为 http://127.0.0.1:8000/mcp/。Claude Code 本仓库已内置项目级 .mcp.json，在本目录启动即自动挂载，也可全局添加；Cursor / TraeWork 及其他支持 MCP 的客户端可在 MCP 配置中加入 JSON（Cursor 放 ~/.cursor/mcp.json 或项目 .cursor/mcp.json；TraeWork 在设置中添加 MCP 服务器）。挂载后可用的 MCP 工具：write_memory / search_memory / read_memory / update_memory / delete_memory / add_document / add_webpage / ask_kb。启用 KB_API_KEY 鉴权后，MCP 客户端需在连接配置加 headers（Authorization: Bearer <key>）；仓库内 .mcp.json 模板不含真实 key。记忆治理（去重/衰减/新鲜度）均默认关闭、零行为变化。全部配置以 KB_ 前缀的环境变量或 .env 文件提供，完整键名见 .env.example（复制为 .env 后填写，.env 已被 gitignore，真实密钥只放本机，严禁入库）。kb ask 直连本地服务逻辑（不经 HTTP），建议 serve 停止时使用，避免双进程写库竞争。
agent-orchestra 是实验性的多 Agent 协作系统，让多个 AI 助手（不同 TraeWork 任务 / Claude Code 会话，模型可不同）通过 kb 共享任务板协作开发：协调者 AI 拆卡分发，worker AI 领卡执行、单卡单轮、回写结果，协调者核验流转。完整使用方法见用户使用手册第 4 节。
相关文档包括：用户使用手册 docs/USER_GUIDE.md、AI 接力文档 PROJECT.md、设计文档 docs/superpowers/specs/2026-08-23-kb-memory-service-design.md、P2 日志设计 docs/superpowers/specs/2026-08-24-logging-design.md、P2 路线图 docs/superpowers/plans/2026-08-24-p2-roadmap.md、节点开发计划 docs/superpowers/plans/2026-08-23-kb-dev-nodes.md、AI 协作规范 AGENTS.md。使用限制方面，agent-orchestra 标注为实验性；文档未提供收费、价格或平台支持的更多信息，暂未提供。
