Skip to content

About

Add repos, and your agent always has them at hand. Local knowledge base with instant search, zero dependencies. MCP server for Claude, Cursor, Gemini, Codex.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

201 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

DocsHaven

License: MIT PyPI version GitHub stars GitHub last commit CI Python Coverage

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

Features

  • 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_index entry
  • 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

Installation

pip install docs-haven

Or with uv (recommended):

uv pip install docs-haven

Or from source:

git clone https://github.com/Cipher208/docs-haven.git
cd docs-haven
uv sync
With test dependencies
uv sync --extra test

How to Use

1. 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"

MCP Tools (32)

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

Comparison

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

FAQ

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.

Architecture

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)

Performance

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

Integrations

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 ✅

Development

# 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

Security

  • 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.

Author

Built with ❤️ by Cipher208

License

MIT

About

Add repos, and your agent always has them at hand. Local knowledge base with instant search, zero dependencies. MCP server for Claude, Cursor, Gemini, Codex.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages