# claude_code_kb_search

**Repository Path**: open_source_base/claude_code_kb_searchclaude_code_kb_search

## Basic Information

- **Project Name**: claude_code_kb_search
- **Description**: 这是一个为 Claude Code 设计的完整知识库管理解决方案，包含 MCP 服务器、可视化 WebUI 管理界面和一键启动功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-05
- **Last Updated**: 2025-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Knowledge Base Management System - Unified Architecture Version

https://gitee.com/open_source_base/claude_code_kb_searchclaude_code_kb_search.git

This is a complete knowledge base management solution designed for Claude Code, featuring unified database architecture, multi-knowledge base support, intelligent search, and visual management interface.

🎉 **Latest Version Features**:
- ✅ **Unified Database Architecture** - Versioned management with automatic upgrades
- ✅ **Multi-Knowledge Base Support** - True multi-knowledge base management, not multiple databases
- ✅ **Intelligent Search System** - Support for keyword, semantic, and hybrid search
- ✅ **Working Directory Association** - Intelligent binding between Claude Code working directories and knowledge bases
- ✅ **Simplified Management** - Unified API interfaces and management tools

## ✨ Core Features

### 🗄️ Unified Database Management
- **Versioned Architecture** - Database schema version control with smooth upgrades
- **Automatic Migration** - Auto-detect version and upgrade to latest architecture on startup
- **Data Security** - Automatic backup before upgrades with rollback support
- **Single Data Source** - Solves the chaos of multiple database files

### 🧠 Multi-Knowledge Base System
- **Knowledge Base Management** - Create and manage multiple independent knowledge bases
- **Working Directory Binding** - Associate knowledge bases with Claude Code working directories
- **Priority Control** - Set search priority for knowledge bases
- **Dynamic Switching** - Automatically switch to relevant knowledge bases based on working directory

### 🔍 Intelligent Search Engine
- **Multiple Search Modes**:
  - Keyword Search - Basic text matching
  - Semantic Search - AI-driven semantic understanding (configurable)
  - Hybrid Search - Best results combining keywords and semantics
- **Search Configuration** - Support for OpenAI, local models, and other AI search backends
- **Result Caching** - Improve performance for repeated queries
- **Configurable Limits** - Customize number of returned results

### 🎛️ WebUI Management Interface
- **Modern Interface** - Responsive design, supports mobile and tablet access
- **Real-time Monitoring** - System control and MCP server status displayed in real-time
- **Knowledge Base Management** - Create, delete, and configure knowledge bases
- **Working Directory Management** - Manage associations between working directories and knowledge bases
- **Search Configuration** - Visual configuration of intelligent search parameters

### 🚀 One-Click Launch System
- **Intelligent Startup** - Auto-check environment and initialize database
- **Multiple Modes** - Full startup, WebUI only, or MCP server only
- **Auto Configuration** - Intelligently generate Claude Code configuration
- **Dependency Check** - Auto-detect and prompt for missing dependencies

## 🏗️ System Architecture

### Database Architecture (v3.0)
```
Main Database (knowledge.db) - Management Database
├── knowledge_bases - Knowledge base metadata
├── claude_workdirs - Claude working directories
├── workdir_knowledge_relations - Working directory-knowledge base associations
├── db_version - Database version management
└── database_info - System metadata

Knowledge Base Files (kb_*.db) - Independent Knowledge Bases
├── knowledge - Knowledge entries
├── db_version - Version information
└── Related indexes and triggers
```

### Component Architecture
```
Unified Database Management Layer
├── DatabaseManager - Core database manager
├── Version Migration System - Automatic upgrade mechanism
└── Data Validation Tools - Integrity checking

Multi-Knowledge Base Business Layer
├── MultiKnowledgeBaseManager - Business logic management
├── Working Directory Management - Intelligent association
└── Knowledge Search Engine - Unified search interface

MCP Service Layer
├── UnifiedKnowledgeBase - Simplified MCP interface
├── Tool Integration - Complete Claude Code tools
└── Error Handling - Unified error handling mechanism

WebUI Presentation Layer
├── Unified API Interface - RESTful design
├── Modern Frontend - Bootstrap + JavaScript
└── Real-time Status Monitoring - Server status tracking
```

## 🚀 Quick Start

### System Requirements
- **Python** 3.10 or higher
- **Operating System** Windows/macOS/Linux
- **Memory** At least 512MB available memory
- **Disk Space** At least 100MB available space

### Install Dependencies

```bash
# Full installation (recommended) - includes all features
pip install -r requirements.txt

# Minimal installation - basic features
pip install -r requirements-minimal.txt

# Development environment - includes testing tools
pip install -r requirements-dev.txt

# Upgrade to latest version
pip install -r requirements.txt --upgrade
```

### One-Click Launch (Recommended)

1. **Run the launcher**
   ```bash
   /bin/launcher.bat  # Windows
   # or
   ./bin//launcher.sh  # Linux/macOS
   ```

2. **Select launch mode**
   - Option 1: **Full Launch** - WebUI + MCP Server + Auto Configuration
   - Option 2: **WebUI Only** - Management interface (development mode)
   - Option 3: **MCP Server Only** - Background service mode

3. **Access management interface**
   - Address: http://127.0.0.1:5500
   - Browser automatically opens showing modern management interface

### Manual Launch

```bash
# 1. Initialize database (first run)
python scripts/setup/init_knowledge.py

# 2. Start WebUI management interface
cd webui
python app.py

# 3. Start MCP server (in another terminal)
python scripts/legacy/knowledge_server_old.py
```

## 🎯 Using with Claude Code

### Automatic Configuration (Recommended)

1. **Launch full system**
   ```bash
   /bin/launcher.bat  # Select option 1
   ```

2. **Auto-generate configuration** - System will automatically:
   - Detect Claude Code configuration file location
   - Generate correct MCP server configuration
   - Provide instructions on how to add to Claude Code

3. **Confirm configuration** - Visit WebUI's "System Information" page to confirm correct configuration

### Manual Configuration

If manual configuration is needed, add the following to your Claude Code configuration file:

```json
{
  "mcpServers": {
    "knowledge-search": {
      "command": "python",
      "args": [
        "your-project-path/knowledge_server.py"
      ],
      "env": {}
    }
  }
}
```

**Configuration file paths**:
- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.claude/claude_desktop_config.json`

## 🛠️ MCP Tool Set

### Basic Knowledge Management Tools

#### `search_knowledge` - Knowledge Search
**Function**: Search for relevant content in associated knowledge bases

**Parameters**:
- `query` (required): Search keywords
- `limit` (optional): Number of results to return, default 10

**Example**: "Search for Python decorator related knowledge"

#### `intelligent_search` - Intelligent Search
**Function**: AI-driven semantic search

**Parameters**:
- `query` (required): Search query
- `search_mode` (optional): Search mode - `keyword`/`semantic`/`hybrid`
- `limit` (optional): Number of results to return, default 5

**Example**: "Use semantic search to find best practices for async programming"

#### `add_knowledge` - Add Knowledge
**Function**: Add new knowledge to specified knowledge base

**Parameters**:
- `kb_id` (required): Target knowledge base ID
- `title` (required): Knowledge title
- `content` (required): Knowledge content
- `category` (optional): Category
- `tags` (optional): Tag list

**Example**: "Add DevOps knowledge about Docker container optimization"

### Knowledge Base Management Tools

#### `list_knowledge_bases` - List Knowledge Bases
**Function**: Display all available knowledge bases and their status

#### `get_workdir_knowledge_bases` - Get Working Directory Knowledge Bases
**Function**: Display knowledge bases associated with current working directory

#### `create_knowledge_base` - Create Knowledge Base
**Function**: Create new knowledge base

**Parameters**:
- `name` (required): Knowledge base name
- `description` (optional): Knowledge base description

### System Management Tools

#### `get_system_info` - System Information
**Function**: Get system status and statistics

## 🎛️ WebUI Management Interface

### Main Feature Modules

#### 📊 Intelligent Dashboard
- **System Statistics** - Knowledge base count, total knowledge entries, working directory association status
- **MCP Status Monitoring** - Real-time MCP server running status
- **Quick Search** - Direct knowledge base search from homepage (can select working directory and knowledge base)
- **Quick Operations** - One-click knowledge base creation, working directory association management, MCP server control

#### 🗄️ Knowledge Base Management
- **Knowledge Base List** - Display all knowledge bases and their status
- **Create Knowledge Base** - Visual creation of new knowledge bases
- **Knowledge Base Configuration** - Modify names, descriptions, priorities
- **Knowledge Statistics** - Detailed statistics for each knowledge base

#### 📁 Working Directory Management
- Claude Code working folder, where the claude command was run. Purpose is for different projects to use different knowledge bases
- **Default Directory Association** - Used for general queries, all uncreated working directories use this associated knowledge base for queries
- **Association Management** - Bind/unbind knowledge bases with working directories, create, modify, delete working directories. MCP queries corresponding knowledge bases based on working directories.
- Paginated knowledge base display, searchable, click to associate/disassociate
- **Priority Settings** - Set knowledge base search priority in selected directories
- **Batch Operations** - Quick configuration of multiple association relationships

#### 🔍 Search Configuration
- **Search Modes** - Configure default search mode (keyword/semantic/hybrid)
- **AI Backend Configuration** - Configure OpenAI API, local models, and custom APIs. Add parameters like url, api_key, model, etc.
- **Result Limits** - Set default search result count
- **Cache Settings** - Configure search result caching strategy

#### 🔧 System Control
- **MCP Server** - Start/stop MCP server
- **MCP Usage Tutorial** - Configuration and testing solutions
- **Database Status** - Display database version and health status
- **System Validation** - One-click system integrity validation
- **Log Viewing** - Real-time system operation log viewing (WebUI and MCP server)

## 🚨 Troubleshooting

### Database Related Issues

#### 🗄️ Duplicate Database Files
**Symptoms**: Multiple `knowledge.db` files found

**Solution**:
```bash
# Run cleanup script (auto-merge data)
python scripts/utils/cleanup_databases_simple.py
```

#### 📊 Version Mismatch
**Symptoms**: Database version too old or upgrade failed

**Solution**:
```bash
# Auto-upgrade to latest version
python database/upgrade_database.py

# Check current version
python -c "from database.database_manager import get_database_manager; print(get_database_manager().get_current_version('knowledge.db'))"
```

#### 🔧 Database Corruption
**Symptoms**: SQLite errors or data read failures

**Solution**:
```bash
# Verify integrity of all knowledge bases
python test_unified_system.py

# Re-initialize (creates backup)
python scripts/setup/init_knowledge.py --force
```

### MCP Server Issues

#### 🔌 Claude Code Connection Failed
**Symptoms**: Claude shows "Unable to connect to MCP server"

**Solution**:
1. Confirm MCP server is running
2. Check if configuration file path uses the new `knowledge_server.py`
3. Verify project path is correct in configuration
4. Check `mcp_server.log` for detailed error information

## 💰 Support & Donation

If you find this project helpful, you can support its development through the following methods:

### 💝 Donation Methods

#### WeChat Pay
<img src="donation/webchat_donation.jpg" alt="WeChat Donation QR Code" width="200"/>

**WeChat Pay**: Scan the QR code above to donate via WeChat Pay

#### Other Methods
- **PayPal**: [https://paypal.me/yourpaypal](https://paypal.me/yourpaypal)
- **GitHub Sponsors**: [https://github.com/sponsors/viaco2ove](https://github.com/sponsors/viaco2ove)

### 🙏 Thank You Message
Thank you for supporting the project! Your donations help maintain and improve this knowledge base management system.

感谢您对项目的支持！您的捐赠有助于维护和改进这个知识库管理系统。

## 📂 Project Structure

```
claude_code_kb_search/
├── 📁 database/                    # Unified database management
│   ├── 📄 database_manager.py      # Core database manager
│   ├── 📄 init_database.py         # Database initialization script
│   ├── 📄 upgrade_database.py      # Database upgrade script
│   ├── 📁 schemas/                 # Database schema files
│   │   └── 📄 current.sql          # Current version complete schema
│   ├── 📁 migrations/              # Version migration scripts
│   │   ├── 📄 migrate_to_1.0.sql   # Upgrade to v1.0
│   │   ├── 📄 migrate_to_2.0.sql   # Upgrade to v2.0
│   │   └── 📄 migrate_to_3.0.sql   # Upgrade to v3.0
│   └── 📁 data/                    # Initial data
│       └── 📄 initial_data.sql     # Sample knowledge data
├── 📄 knowledge_server.py          # Unified MCP server
├── 📄 multi_knowledge_base_manager.py # Multi-knowledge base manager
├── 📄 search_config.py             # Search configuration management
├── 📄 ai_search.py                 # AI search engine
├── 📁 webui/                       # WebUI management interface
│   ├── 📄 app.py                   # Unified architecture Flask app
│   ├── 📁 templates/               # Updated template files
│   │   ├── 📄 index.html           # Modern dashboard
│   │   ├── 📄 knowledge_bases.html # Knowledge base management
│   │   ├── 📄 workdir_relations.html # Working directory management
│   │   └── 📄 search_config.html   # Search configuration
│   └── 📁 static/                  # Static resources
├── 📁 donation/                    # Donation related files
│   └── 📄 webchat_donation.jpg     # WeChat donation QR code
├── 📄 /bin/launcher.bat                 # Intelligent launcher (recommended)
├── 📄 knowledge.db                 # Main management database
├── 📄 DATABASE_ARCHITECTURE.md     # New architecture detailed documentation
├── 📄 test_unified_system.py       # Unified system testing
└── 📄 requirements.txt             # Complete dependency list
```

## 💡 Performance Optimization Tips

### Database Optimization
- **Index Optimization** - System automatically creates necessary indexes
- **Regular Maintenance** - Periodically run `VACUUM` to clean database
- **Batch Operations** - Use transactions for large data imports

### Search Optimization
- **Result Caching** - Enable intelligent search result caching
- **Concurrency Limits** - Control number of simultaneous search requests
- **Mode Selection** - Choose the most suitable search mode based on needs

### System Optimization
- **Memory Management** - Monitor memory usage of long-running services
- **Log Rotation** - Regularly clean oversized log files
- **Resource Monitoring** - Use WebUI to monitor system resource status

## 🔮 Upcoming Features

Features coming soon (in development):
- 🧠 **Vector Search** - Advanced semantic search based on embeddings
- 📄 **Document Import** - Direct import of PDF, Word, and other documents
- 🔄 **Real-time Sync** - Multi-client real-time data synchronization
- 🎨 **Theme Customization** - WebUI appearance theme customization
- 📊 **Advanced Analytics** - Knowledge base usage analytics
- 🚀 **Performance Mode** - High-performance search and caching strategies

## 📞 Technical Support

If you encounter issues:

1. **Check Logs** - Real-time log viewing in WebUI
2. **Run Tests** - `python test_unified_system.py` for system checks
3. **View Documentation** - `DATABASE_ARCHITECTURE.md` for detailed technical documentation
4. **System Validation** - "System Validation" feature in WebUI

**Upgrade Notice**: If you're upgrading from an older version, the system will automatically handle data migration, but we recommend backing up important data first.

---

## 🎯 Summary

This unified architecture version solves the main problems of the original system:
- ✅ **Database Chaos** → Unified management with version control
- ✅ **Multiple Database Issues** → True multi-knowledge base architecture
- ✅ **Scattered Features** → Unified API and management interface
- ✅ **Difficult Upgrades** → Auto-detection and seamless upgrades
- ✅ **Complex Configuration** → One-click launch and intelligent configuration

**Get Started Now**: Run `/bin/launcher.bat` to experience the new unified knowledge base management system! 🚀

### Donation Methods
The project has integrated donation functionality. You can support us through:

- **WeChat Pay**:
- <img src="donation/webchat_donation.jpg" alt="WeChat Pay QR Code" width="200">

Thank you for your support!

## 📄 License
MIT License - See LICENSE file for details