Your AI agent keeps forgetting what it learned last session. DocsHaven fixes that.
Add your repos, and your agent always has them at hand. DocsHaven is a local knowledge base that lets you index any GitHub repository, search it instantly, and keep your agent informed across sessions. Works with any MCP-compatible agent — Claude, Cursor, Gemini, Codex.
Why DocsHaven?
- 🧠 Add repos once, search forever — your agent always has the knowledge it needs
- ⚡ Instant search — SQLite FTS5 finds relevant docs in milliseconds
- 🔌 Works with any AI agent — Claude, Cursor, Gemini, Codex via MCP
- 🏠 100% local — no cloud, no API keys, no data leaves your machine
- 📦 Minimal dependencies — only
mcp[cli], no Docker or external services
- SQLite FTS5 search — BM25 ranking with LIKE fallback, score explanation
- URI routing — organize knowledge by domain:
core://,ref://,guide:// - Git sync — compressed chunks for multi-machine sync (no merge conflicts)
- Conflict detection — flag contradictions when adding documents
- Source indexing — GitHub repos, local folders, web pages and PyPI package docs through one
kb_indexentry - MCP server — 32 tools for any MCP-compatible agent
- Document chunking — split long documents for better search precision
- Result type — Pydantic v2 models with Ok/Err pattern
- Input validation — URL, collection names, query length validated
pip install docs-havenOr with uv (recommended):
uv pip install docs-havenOr from source:
git clone https://github.com/Cipher208/docs-haven.git
cd docs-haven
uv syncWith test dependencies
uv sync --extra test1. Add Repositories to Your Knowledge Base
from storage import Storage
from pathlib import Path
storage = Storage(Path.home() / ".docshaven")
# Add a GitHub repo (clones and indexes markdown files)
result = storage.add_repo(
url="https://github.com/fastapi/fastapi",
description="FastAPI web framework",
)
print(f"Indexed {result['files_indexed']} files in {result['chunks']} chunks")
# Add with custom file mask (index Python files)
result = storage.add_repo(
url="https://github.com/pallets/flask",
mask="**/*.py",
)2. Search Your Knowledge Base
# Basic search
results = storage.search("dependency injection")
for r in results:
print(f"{r['score']:.2f} [{r['collection']}] {r['title']}")
print(f" {r['content'][:100]}...")
print()
# Search with filters
results = storage.search(
"async middleware",
collections=["fastapi"],
limit=5,
min_score=0.3,
)
# Use auto strategy (fts for short queries, hybrid for long)
results = storage.search("how to use Depends()", strategy="auto")3. Organize with URI Routing
from uri import URI, URIRouter
# Parse URIs
uri = URI.parse("core://fastapi/dependencies")
print(uri.domain) # "core"
print(uri.path) # "fastapi/dependencies"
print(uri.to_collection()) # "core__fastapi"
# Search within a URI scope
router = URIRouter(storage)
results = router.search_by_uri("core://fastapi", limit=5)
# List all domains
domains = router.list_all_domains()
# {'core': {'count': 3, 'doc': 'Core documentation'}, 'ref': {'count': 2, ...}}Available domains: core, ref, guide, lib, src, test, note
4. Detect Conflicts
from conflicts import ConflictDetector
detector = ConflictDetector(storage)
result = detector.detect(
title="FastAPI dependency injection",
content="How to use Depends()...",
)
if result.has_conflicts:
print(f"Found {len(result.candidates)} similar documents:")
for c in result.candidates:
print(f" - {c['title']} (score: {c['score']})")
print(f" {c['snippet'][:80]}...")
# Record judgment
detector.judge("new_doc_id", "existing_doc_id", "supersedes")5. Sync Between Machines
from sync import Syncer
from pathlib import Path
syncer = Syncer(Path.home() / ".docshaven-sync")
# On machine A: export
result = syncer.export(
{"fastapi": docs, "sqlalchemy": docs},
created_by="alice",
)
print(f"Exported chunk {result['chunk_id']}")
# On machine B: import
result = syncer.import_chunks()
print(f"Imported {result['chunks_imported']} chunks")
# Check status
status = syncer.status()
print(f"Chunks: {status['local_chunks']}")6. Use as MCP Server
Add to your MCP client config (Claude Desktop, Cursor, etc.):
{
"mcpServers": {
"docs-haven": {
"command": "python",
"args": ["/path/to/docs-haven/server.py"]
}
}
}Then ask your agent:
"Search for FastAPI middleware examples" "What documentation do we have about SQLAlchemy?" "Check if this new doc conflicts with existing ones"
| Tool | Description |
|---|---|
kb_search |
Search with BM25 ranking + highlighted excerpts |
kb_ask |
Natural-language answers with citations (host LLM) |
kb_related |
Related documents for a stored document |
kb_recent |
Recently accessed documents |
kb_learn |
Topic exploration: collections, key docs, learning path |
kb_add_repo |
Clone and index a GitHub repo |
kb_index |
Index any source — local folder, GitHub repo, web page, plain text or PyPI package docs (auto-detect) |
kb_bookmark |
Save/update a bookmark (URL + title/note) |
kb_bookmarks |
List bookmarks, most recent first |
kb_get |
Get document content |
kb_update |
Update document content (scoped; metadata preserved) |
kb_delete |
Delete document (scoped, never mass-deletes) |
kb_list_collections |
List all collections |
kb_stats |
Database statistics |
kb_collection_rename |
Rename a collection |
kb_check_imports |
Validate a file's imports against real modules |
kb_context_add |
Add context attachment |
kb_context_list |
List context attachments |
kb_context_rm |
Remove context attachment |
kb_uri_resolve |
URI to collection mapping |
kb_uri_search |
Search within URI scope (supports wildcards) |
kb_uri_list |
List URIs in domain |
kb_uri_domains |
All domains with counts |
kb_sync_export |
Export compressed chunk |
kb_sync_import |
Import chunks |
kb_sync_status |
Sync status |
kb_conflict_check |
Detect conflicts |
kb_conflict_judge |
Record judgment |
kb_conflict_details |
Conflict details for resolution |
kb_conflict_suggest |
Suggest resolution strategy |
kb_template_list |
List collection templates |
kb_template_apply |
Apply a collection template |
| Feature | DocsHaven | QMD | Elasticsearch | Context7 |
|---|---|---|---|---|
| Dependencies | 1 (mcp) | 1 (npm) | JVM + plugins | External service |
| MCP server | Built-in | No | No | Yes |
| URI routing | Yes | No | No | No |
| Conflict detection | Yes | No | No | No |
| Git sync | Compressed chunks | No | No | No |
| Cost | Free | Free | Free (self-hosted) | Paid tiers |
What is DocsHaven?
DocsHaven is a local knowledge base designed for AI agents. It provides full-text search via SQLite FTS5, organizes knowledge by URI domains (core://, ref://, guide://), and detects contradictions when adding new documents. It runs as an MCP server with 32 tools.
How is this different from just using SQLite?
DocsHaven adds a complete knowledge management layer on top of SQLite: automatic document chunking, BM25 ranking with LIKE fallback, URI-based organization, conflict detection, and compressed multi-machine sync — all exposed via MCP tools.
Can I use this with Claude Desktop / Cursor / other AI agents?
Yes. DocsHaven runs as an MCP server. Add it to your MCP client config and all 32 tools become available to your agent.
How fast is search?
SQLite FTS5 with BM25 ranking is fast on local libraries: in the bundled benchmark (uv run python benchmark.py --json, 1,000 documents, 1,000 queries) the average query takes 9.8ms (P95 52.8ms). No network latency since everything is local.
Is my data sent anywhere?
No. DocsHaven is fully local. The only network operation is cloning GitHub repositories (which you initiate). All search and storage happens on your machine.
docs-haven/
├── server.py # MCP server (32 tools, native argument aliases on hot tools)
├── storage.py # SQLite FTS5 backend + Result types
├── scoring.py # BM25/lexical scoring + boosts
├── chunking.py # Document chunking (text + code-aware)
├── validation.py # Input validation
├── vector.py # TF-IDF vector search (optional)
├── uri.py # URI routing
├── sync.py # Git sync (compressed chunks)
├── conflicts.py # Conflict detection
├── llm.py # LLM integration via MCP host (kb_ask)
├── result.py # Ok/Err Result type (Pydantic v2)
├── cli.py # CLI interface (13 commands)
├── templates.py # Collection templates
├── import_guard.py # Import validation
├── benchmark.py # Performance benchmarks
├── tests/ # pytest test suite (609 tests)
├── docs/ # Documentation + 10 ADRs
└── pyproject.toml # Package config (uv)
Measured with uv run python benchmark.py --json (Python 3.11, SQLite 3.50 — one example run; same-machine runs vary by ~25-40%):
| Operation | Time |
|---|---|
| Index 100 docs | 0.035s (2,847 docs/sec) |
| Index 500 docs | 0.199s (2,512 docs/sec) |
| Index 1,000 docs | 0.369s (2,711 docs/sec) |
| Search (avg) | 9.8ms |
| Search (P95) | 52.8ms |
| Throughput | 102 queries/sec |
Run benchmark: uv run python benchmark.py --json
| Client | Config | Status |
|---|---|---|
| Claude Desktop | claude_desktop_config.json |
✅ |
| Cursor | .cursor/mcp.json |
✅ |
| Gemini CLI | gemini mcp add |
✅ |
| VS Code (Copilot) | .vscode/mcp.json |
✅ |
| Codex | .codex/config.toml |
✅ |
# Install with test dependencies
uv sync --extra test
# Run tests
uv run pytest tests/ -v
# Run linting
uv run ruff check .
# Run formatting
uv run ruff format .
# Run type checking
uv run mypy . --ignore-missing-imports
# Run coverage
uv run pytest tests/ --cov --cov-report=term-missing- SQLite FTS5 with parameterized queries (no SQL injection)
- Input validation on all MCP tool parameters
- No external network dependencies (local-only operation)
- Secret scanning via GitHub Actions (gitleaks)
See SECURITY.md for vulnerability reporting.
Built with ❤️ by Cipher208
MIT