rag-kb is a local-first, fully offline-capable Agent memory and knowledge service. It uses a dual REST + MCP protocol and provides hybrid retrieval (normalized weighted fusion of vectors + BM25), document/webpage ingestion, and RAG question answering; storage/retrieval and search remain fully usable without an LLM. The repository contains two subsystems (kb and agent-orchestra), and the open-source license is Apache-2.0 (including patent grant, commercially usable).
In terms of purpose, kb is aimed at Claude Code / Cursor / TraeWork / self-built Agents, providing memory writing, document and webpage ingestion, hybrid retrieval, and RAG question answering, and runs as a Windows single-process resident service (python -m kb serve).
Main capabilities include: single-process resident service, where one python -m kb serve simultaneously provides the REST API and MCP endpoint; hybrid retrieval, BGE-M3 vector retrieval + BM25 keyword retrieval, with each path min-max normalized and then fused and ranked with equal weights according to the number of active paths, with friendly Chinese tokenization; optional reranking, set KB_RERANK_ENABLED=true to enable bge-reranker-v2-m3 cross-reranking (off by default); optional third path, set KB_SPARSE_ENABLED=true to enable the BGE-M3 sparse vector third path (off by default, automatically degrades to two paths on failure); memory management, supporting write/update/delete/list, and filtering by namespace, tags, and type; fully shared memory (v3), local single-user positioning, all memory/knowledge is fully shared with any client, task, or AI, client/project are only used for audit categorization and metadata, and the primary key is generated server-side; access auditing, each write/read/update/delete/retrieval/question-answer records JSON to logs/agent-audit/<client>__<project>.log, which can be queried via REST GET /api/v1/audit?client=<client>[&project=<project>] or CLI kb audit --client <client>; knowledge ingestion, supporting upload or path import of local documents (txt/md/pdf/docx, etc.), as well as webpage body scraping and ingestion; directory watching, automatically ingesting/cleaning up newly added/deleted files in the directory specified by KB_WATCH_DIR; CLI tools, kb add/search/stats/ask/eval/forget/dedup; privacy guardrails, sensitive namespaces are forced to answer locally without going online, /ask intelligently routes with local priority and optional cloud for difficult problems; usable when offline, with models and data all stored locally.
In terms of usage, installation requires creating a virtual environment on Windows / Linux / macOS and then installing dependencies; the kb command is installed only inside the virtual environment, and every new terminal must first activate the virtual environment (on Windows use .\venv\Scripts\Activate.ps1, on Linux/macOS use source venv/bin/activate), otherwise it will report that the kb command is not found; using python -m kb <subcommand> instead can bypass activation. An alternative is installation without a virtual environment (Python 3.10+): after pip install --user -r requirements.txt, run with python -m kb serve, but it is recommended to prioritize venv for dependency isolation. The first startup will load the local embedding model (default BAAI/bge-m3, about 2GB, needs to be downloaded and cached in advance); when no LLM is configured, the service starts as usual, and /ask returns 503 with configuration guidance. LLM is disabled by default (KB_LLM_MODE=off), and service startup will not probe/load/call any large model, with zero VRAM, zero cost, and pure offline. When RAG question answering is needed, you can configure a local LLM (Ollama) or a cloud LLM (any OpenAI-compatible provider, not tied to DeepSeek; DeepSeek / OpenAI / Tongyi Qianwen / SiliconFlow / Moonshot, etc. are all fine, with universal three keys). The verification method is the llm field of GET /api/v1/healthz: local / cloud means ready, disabled means not enabled. Direct connection to huggingface.co from mainland China will time out; you can set an HF mirror and restart: export HF_ENDPOINT=https://hf-mirror.com，或写入 ~/.bashrc takes effect permanently; the model is automatically downloaded from the mirror and cached to ~/.cache/huggingface/hub/, after which it can be loaded offline even without a network connection. When the model is already cached locally but there is no external network, kb adopts offline-first (it hits the local cache first and only goes online if that fails), so as long as the cache directory is complete it can run fully offline.
Agent integration is client-agnostic: installing the skill is recommended (the skills/kb-memory/SKILL.md in the repository is a client-agnostic Anthropic open-format skill; after copying it to the user-level skills directory of the client you use, any project session of that client will automatically recognize and trigger it when reading/writing memory, doing RAG Q&A, or auditing queries; installing means copying the directory, and if there is a script you can also copy manually, with no dependencies; see scripts/README.md for update, uninstall and usage instructions); not installing it does not affect the kb service, and a plain-text prompt can serve as a fallback: copy the entire docs/AGENT_PROMPT.md and paste it to the Agent, and it works with any client. Note that .trae-cn/skills, .claude/skills, .cursor/skills are not unified standard directories, but merely user-level convention directories of each client; SKILL.md itself is in the unified Anthropic open format, but which directory it is installed to and whether it can be auto-triggered are decided by each client itself, with varying degrees of support.
The MCP endpoint (streamable HTTP) is http://127.0.0.1:8000/mcp/。Claude Code. This repository has a built-in project-level .mcp.json, which is automatically mounted when started in this directory, and it can also be added globally; Cursor / TraeWork and other clients that support MCP can add JSON to the MCP configuration (for Cursor, put it in ~/.cursor/mcp.json or the project's .cursor/mcp.json; for TraeWork, add the MCP server in settings). The MCP tools available after mounting: write_memory / search_memory / read_memory / update_memory / delete_memory / add_document / add_webpage / ask_kb. After enabling KB_API_KEY authentication, MCP clients need to add headers to the connection configuration (Authorization: Bearer <key>); the .mcp.json template in the repository does not contain a real key. Memory governance (deduplication/decay/freshness) is disabled by default with zero behavior change. All configuration is provided via environment variables with the KB_ prefix or a .env file; see .env.example for the full key names (copy it to .env and fill it in; .env is already gitignored, and real keys should only be kept locally and are strictly forbidden from being committed to the repository). kb ask connects directly to the local service logic (without going through HTTP), and is recommended for use when serve is stopped, to avoid two processes competing to write to the database.
agent-orchestra is an experimental multi-Agent collaboration system that lets multiple AI assistants (different TraeWork tasks / Claude Code sessions, possibly with different models) collaborate on development through a kb-shared task board: the coordinator AI splits cards and distributes them, worker AIs claim cards and execute them, one card per round, and write back results, while the coordinator verifies and moves them along. See Section 4 of the user manual for full usage instructions.
Related documents include: the user manual docs/USER_GUIDE.md, the AI relay document PROJECT.md, the design document docs/superpowers/specs/2026-08-23-kb-memory-service-design.md, the P2 logging design docs/superpowers/specs/2026-08-24-logging-design.md, the P2 roadmap docs/superpowers/plans/2026-08-24-p2-roadmap.md, the node development plan docs/superpowers/plans/2026-08-23-kb-dev-nodes.md, and the AI collaboration specification AGENTS.md. Regarding usage restrictions, agent-orchestra is marked as experimental; the documentation does not provide further information on pricing, cost, or platform support, and none is currently provided.
