docmind

Local Deep Research knowledge base for coding agents.

Point docmind at any folder of documents. Your agent gets three MCP tools:

| Tool | What it does | Cost | |------|-------------|------| | search | Instant hybrid retrieval (BM25 + vectors + ripgrep) | Free, sub-second | | research | Budgeted LLM deep-dive with source citations, auto-saved as a knowledge note | LLM tokens | | remember | Persist a fact/decision/summary into the knowledge base | Free |

The flywheel: every research conclusion is saved and indexed, so tomorrow's search answers instantly what today's research had to work for.

Quick start

Single self-contained package (~180 KB, zero npm dependencies — everything runs locally):

# Step 1 — install (`npx --package docmind-mcp docmind init` works without global install)
npm install -g docmind-mcp

# Step 2 — one wizard sets up everything and wires your agent
docmind init

What docmind init asks you (step by step)

Step 1/4 — Dependencies. Scans and installs zvec-grep, ripgrep-all, CPU-only pytorch, and sirchmunk (avoids the 3-4 GB CUDA download trap). Items marked MISS get installed automatically; you can also install them manually and re-run init. ripgrep must exist beforehand (apt install ripgrep / brew install ripgrep).

Step 2/4 — Knowledge folder. Any folder of documents you want your agent to know about: markdown, PDFs, docx, source code, notes. Example: ~/docs/my-project. Everything is indexed in place — docmind never copies or modifies your files.

Step 3/4 — LLM credentials (for research mode). Paste key, base URL and model in any format, for example:

key=sk-xxx Base url=https://api.example.com/v1 Model name=my-model

Free tiers work fine — e.g. Zhipu (https://open.bigmodel.cn/api/paas/v4, model glm-4.7-flash) or any OpenAI-compatible endpoint. Press Enter to skip; search still works without any LLM, and you can run docmind init again later to add it. Credentials are stored in ~/.sirchmunk/.env (permission 600).

Step 4/4 — Service start + agent wiring. Starts the research engine in the background and registers the MCP server into your coding agent.

After init, your agent immediately has search / research / remember. Verify anytime with docmind doctor.

Connect your agent

docmind install                # auto-tries opencode, claude-code, codex
docmind install --target opencode
docmind install --target claude-code
docmind install --target codex
docmind install --target generic   # prints the JSON for any other agent

Manual registration, if you prefer — the MCP server is a plain stdio process:

{ "docmind": { "command": "docmind-mcp", "env": { "DOCMIND_ROOT": "/path/to/your/docs" } } }

• opencode: add to the mcp section of ~/.config/opencode/opencode.json
• claude-code: add to mcpServers in ~/.claude.json (or run claude mcp add)
• codex: add to mcp_servers in ~/.codex/config.toml

Everyday commands

docmind status          # is the research engine up?
docmind doctor          # full health check of the whole chain
docmind up / down       # start / stop the background research engine
docmind search "query"  # quick terminal search, no agent needed
docmind index           # rebuild the search index after bulk-importing files

How your agent uses it

• "Where is X documented?" → search (free, instant)
• "Summarize / compare / explain why..." → research (LLM budget, saves the conclusion)
• "Remember this: ..." → remember (teaches your knowledge base)

Each tool call accepts an optional root parameter to target a different folder — one docmind instance can serve multiple knowledge bases.

How it works

Agent ──MCP stdio── docmind
                     ├── search   → zvec-grep (BM25 + vectors + ripgrep, local index in <root>/.zvec-grep)
                     │              + OpenViking memory recall (optional)
                     ├── research → Sirchmunk (budgeted LLM evidence exploration, http://127.0.0.1:8584)
                     └── remember → markdown notes in <root>/.knowledge/ (frontmatter-tagged, git-friendly)

• Retrieval is fully local; only research calls your LLM, with a hard token budget per query.
• Knowledge notes are plain markdown — readable, editable, versionable.
• Hidden folders (.zvec-grep/, .knowledge/) are indexed for search but excluded from research scans.

Semantic memory with OpenViking (optional)

If an OpenViking server is running at http://127.0.0.1:1933, docmind automatically layers semantic memory on top of your knowledge base:

| Capability | What it adds | |------------|-------------| | Auto memory capture | Every research conclusion and remember note is distilled by OpenViking into structured long-term memories (preferences, entities, events) — no agent discipline required | | Memory-first recall | search / research inject a compact (<300 token) context block of relevant memories and document summaries before raw hits | | Semantic folder mirror | Your knowledge folder is mirrored to viking://resources/docmind/... (incremental, mtime-based), giving cross-document semantic search that understands Chinese and English queries |

Without OpenViking, docmind works exactly the same as before — it probes the server on every call and degrades silently.

Installing OpenViking

docmind never installs OpenViking for you. To enable the optional layer:

# 1. Install (Python 3.10+)
pip install openviking

# 2. Create ~/.openviking/ov.conf — point it at any OpenAI-compatible LLM endpoint.
#    Free tiers are fine; a text-only model covers document workflows.
#    Embedding needs a real embedding endpoint (here: SiliconFlow bge-m3).

~/.openviking/ov.conf:

{
  "vlm": {
    "provider": "openai",
    "model": "glm-4.7-flash",
    "api_base": "https://open.bigmodel.cn/api/paas/v4",
    "api_key": "sk-your-key-here",
    "max_retries": 8
  },
  "embedding": {
    "dense": {
      "provider": "openai",
      "model": "BAAI/bge-m3",
      "api_base": "https://api.siliconflow.cn/v1",
      "api_key": "sk-your-key-here",
      "dim": 1024
    }
  }
}

# 3. Start the server (keep it running in the background)
openviking-server --config ~/.openviking/ov.conf

# 4. Verify
curl http://127.0.0.1:1933/ready    # expect 200
docmind doctor                      # openviking line should show [ok]

Note: OpenViking is AGPL-3.0. docmind interoperates over HTTP only and ships none of its code.

Note: changing the embedding model requires resetting ~/.openviking/data (embeddings are dimension-locked).

How syncing behaves

• docmind hands files to OpenViking's durable task queue and records progress immediately; the server digests them in the background. First sync of a large repo takes a while — the server makes one or more LLM calls per file, and rate-limited free tiers slow that down to roughly 10-20 files per 30 minutes. It keeps digesting after you walk away; re-runs only enqueue what changed.
• Binary/media/lock files (png, pdf, zip, log, xsd, ... — see the OV_SKIP_EXTS list in src/ov-bridge.ts) are never mirrored.
• Your folder stays the single source of truth — OpenViking is a read-through semantic mirror, and .zvec-grep/ / .knowledge/ internals are never synced.
• Memory extraction (research / remember distillation) is best-effort: under aggressive rate limiting a session commit may fail silently. Your notes stay safe in <root>/.knowledge/ regardless.

Environment override: DOCMIND_OPENVIKING_URL (default http://127.0.0.1:1933).

Configuration reference

~/.docmind/config.json

{
  "defaultRoot": "/path/to/your/docs",
  "sirchmunkUrl": "http://127.0.0.1:8584",
  "researchTimeoutSec": 120,
  "searchTimeoutSec": 30
}

| Field | Meaning | |-------|---------| | defaultRoot | knowledge base used when a tool call has no root argument | | sirchmunkUrl | research engine endpoint | | researchTimeoutSec | per-query budget ceiling for research | | searchTimeoutSec | per-query ceiling for search |

~/.sirchmunk/.env (research LLM)

LLM_API_KEY=sk-your-key-here
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
LLM_MODEL_NAME=glm-4.7-flash

Any OpenAI-compatible endpoint works. Restart the engine after editing: docmind down && docmind up.

Environment variables

| Variable | Overrides | |----------|-----------| | DOCMIND_ROOT | defaultRoot | | SIRCHMUNK_URL | sirchmunkUrl | | DOCMIND_OPENVIKING_URL | OpenViking endpoint |

~/.docmind/ov-state.json

Auto-managed mirror sync state — do not edit while a sync is running. Delete it to force a full re-mirror on the next run.

Troubleshooting

Run docmind doctor first — it checks the whole chain and prints one line per component ([ok] / [!!] / [--] for optional-but-off):

| Symptom | Cause & fix | |---------|-------------| | doctor shows research engine [!!] not running | Run docmind up. Right after start it may still be loading models — wait a minute and check again. | | research returns degraded/fast answers | No LLM configured, or the endpoint is rate-limiting. Check ~/.sirchmunk/.env, then docmind down && docmind up. Free tiers throttle under load; retry later or switch model. | | search finds nothing new | Index is stale after bulk import — run docmind index. | | OpenViking line shows [--] not running | Optional layer is off. Start openviking-server to enable; otherwise ignore. | | OpenViking mirror is behind your files | Expected during first sync (server digests in background, see above). It catches up on its own. | | OpenViking fails to start with an embedding error | Embedding model/dimension changed — back up and reset ~/.openviking/data, then restart. | | ripgrep-all install fails on macOS | Automatic install covers linux/x64 only; run brew install ripgrep-all. |

Requirements

• Node.js >= 18.17
• Python 3.10+ with pip (for the research engine)
• Linux x64 or macOS (automatic ripgrep-all install currently covers linux/x64; on macOS run brew install ripgrep-all)
• OpenViking (optional): Python 3.10+ and an OpenAI-compatible LLM endpoint

Sources

Built on two Apache-2.0 engines:

• zvec-grep — local hybrid retrieval
• Sirchmunk — indexless agentic search (LENS)

Optional semantic-memory layer:

• OpenViking — context database (AGPL-3.0; docmind interoperates over HTTP only and ships none of its code)