claude-kb 0.5.0

Universal knowledge base with Qdrant for Claude Code integration

Claude KB

Universal knowledge base with Qdrant for Claude Code integration.

Provides semantic search across:

• Claude Code conversation history
• Personal knowledge entities
• Documents and research notes

Installation

Run directly (no install)

uvx claude-kb@latest status

Install as a tool

uv tool install claude-kb
kb status

# Update to latest version
uv tool upgrade claude-kb

Development

git clone https://github.com/tenequm/claude-kb.git
cd claude-kb
uv sync --extra dev

Features

• Hybrid search: Dense (semantic) + sparse (keyword) vectors with RRF fusion
• Claude Code import: Automatically import your conversation history
• LLM-optimized CLI: kb ai command provides token-efficient schema for AI agents
• FastEmbed/ONNX: Fast local embeddings with bge-base-en-v1.5 (768 dim, ~1s search time)
• Self-hosted: Run locally with Docker Compose

Quick Start

# Start Qdrant
docker compose up -d

# Initialize collections
kb init

# Import your Claude Code conversations
kb import claude-code-chats

# Search!
kb search "qdrant vector databases"

Usage

Search conversations

kb search "your query"
kb search "query" --collection conversations --limit 20

Get specific message

kb get msg_abc123

Check status

kb status

LLM-optimized schema (for AI agents)

kb ai

This outputs a token-efficient format that Claude Code and other LLMs can parse to understand how to use the CLI. See docs/AI_COMMAND_SPEC.md for details.

MCP Server

Claude KB provides an MCP server for integration with Claude Code:

# Add to Claude Code
claude mcp add kb -- uv run kb mcp

# Or run standalone
uv run kb mcp

Understanding Search Results

Score Interpretation

• 0.9+: Very high relevance (exact topic match)
• 0.7-0.9: Good match (related concepts)
• 0.5-0.7: Moderate match (partial relevance)
• <0.5: Filtered out by default

Why results might be empty

1. min_score too high (default 0.5) - try lowering to 0.3
2. Query too specific - use broader conceptual terms
3. Project filter doesn't match - it's a partial, case-sensitive match
4. No data imported - run kb status to verify

Content visibility

• All content is indexed and searchable (including tool results and thinking blocks)
• By default, output shows placeholders: [tool result: N chars], [thinking: N chars]
• Use include_tool_results=True or include_thinking=True to see full content

Filter Application Order

Filters are applied in this sequence:

1. Semantic search + min_score (server-side in Qdrant)
2. Metadata filters (project, role, from_date, to_date) (server-side)
3. Recency boost (if enabled)
4. Limit applied

This means if min_score filters out results, date filters never see them.

Architecture

• Simplified structure: cli.py, core.py, import_claude.py (No manual embedding code!)
• Qdrant collections: conversations, entities, documents
• Embedding: QdrantClient built-in FastEmbed with BAAI/bge-base-en-v1.5 (768 dim, ONNX-optimized)
• Search time: ~1 second total (0.7s model load + 0.3s search)
• Output format: Structured plaintext (NOT JSON) optimized for LLM parsing

Configuration

Create .env file (see .env.example):

QDRANT_URL=http://localhost:6333
EMBEDDING_MODEL=BAAI/bge-base-en-v1.5  # FastEmbed model (768 dims, ~1s search)

# Alternative models:
# EMBEDDING_MODEL=BAAI/bge-small-en-v1.5  # Faster (384 dims, ~0.5s)
# EMBEDDING_MODEL=BAAI/bge-large-en-v1.5  # Higher quality (1024 dims, ~2s)

Development

# Format + lint
ruff format . && ruff check . --fix

# Test (manual for now)
uv run kb --help

Roadmap

• Streaming search (background mode)
• Entity management (kb add entity)
• Document import (kb add document)
• Relationship traversal (kb related)
• Full hybrid search (sparse vectors)
• Token-aware context window truncation

License

MIT