内容
# 知识库系统 - 使用 Python、PostgreSQL & pgvector 进行语义搜索
开源 AI 知识库，具有语义搜索、向量嵌入和 Claude MCP 集成。使用 Python 和 PostgreSQL pgvector 构建，用于 LLM 驱动的文档检索。
**特性：**
- **语义搜索** - 使用 OpenAI (text-embedding-3-small) 的向量嵌入
- **PostgreSQL + pgvector** - 向量相似性操作和全文搜索
- **Claude MCP 集成** - 用于 Claude Code/Desktop 的模型上下文协议服务器
- **RAG Agent CLI** - 具有查询改进的交互式终端代理 (Google Gemini)
- **Python 工具包** - 具有类型提示的简洁、模块化 API
- **异步操作** - 数据库优先写入，具有后台文件同步
---
## 系统架构
```
Claude Code / Claude Desktop Terminal (kbagent)
│ │
▼ ▼
MCP Server (mcp_server.py) RAG Agent (rag_agent.py)
├─ search_summaries() ├─ Query improvement (Gemini)
├─ fetch_document() ├─ Document-only responses
├─ save_knowledge() └─ Interactive CLI
├─ update_document() │
├─ delete_document() │
└─ list_categories() │
│ │
└──────────────┬───────────────────┘
▼
Knowledge Toolkit (toolkit.py)
├─ search_summaries_tool()
├─ fetch_document_tool()
├─ knowledge_store_tool()
├─ update_document_tool()
├─ delete_document_tool()
└─ knowledge_list_categories()
│
▼
PostgreSQL + pgvector
├─ documents (full content)
├─ summaries (embeddings)
└─ vector indexes
```
---
## 快速入门指南
### 1. Python 设置
```bash
git clone <repo>
cd knowledge-base
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. 数据库设置
**Supabase (Cloud):**
```bash
# 1. 在 Supabase 上创建 PostgreSQL 实例
# 2. 在 SQL 编辑器中运行 schema.sql
# 3. 从设置中复制连接字符串
```
**Local Docker:**
```bash
docker-compose up -d
psql -h localhost -U db_user -d knowledge -f schema.sql
```
### 3. 配置 MCP Server
添加到您的 MCP 配置：
```json
{
"mcpServers": {
"knowledge-base": {
"type": "stdio",
"command": "python",
"args": ["src/knowledge_base/mcp_server.py"],
"env": {
"DATABASE_URL": "${DATABASE_URL}",
"OPENAI_API_KEY": "${OPENAI_API_KEY}",
"ENABLE_FILE_OPERATIONS": "${ENABLE_FILE_OPERATIONS:-true}",
"KNOWLEDGE_DIR": "${KNOWLEDGE_DIR:-./knowledge}"
}
}
}
}
```
或者使用 CLI：
```bash
claude mcp add --transport stdio knowledge-base \
--env DATABASE_URL="postgresql://user:password@host:5432/database" \
--env OPENAI_API_KEY="sk-..." \
-- python src/knowledge_base/mcp_server.py
```
在配置中使用绝对路径。有关详细信息，请参见 [.env.example](.env.example)。
现在问 Claude：“Search my knowledge base for X”
### 4. RAG Agent CLI (kbagent)
具有查询改进和基于文档的响应的交互式终端代理。
**安装：**
```bash
# 在激活 venv 的项目目录中
pip install -e .
# 对于全局访问，添加到 ~/.zshrc 或 ~/.bashrc：
alias kbagent="/path/to/knowledge-base/.venv/bin/kbagent"
```
**用法：**
```bash
# 交互模式
kbagent
# 单个查询
kbagent "What is semantic search?"
```
**特性：**
- 查询改进：阐明不清楚的问题，增强查询以获得更好的搜索
- 仅文档响应：严格从知识库内容回答
- 具有相关性分数的来源归属
- 命令：`/help`、`/categories`、`/quit`
**示例会话：**
```
$ kbagent
Knowledge Base Agent
Type your question or /help for commands
You: python best practices
Analyzing query...
Based on the knowledge base documents, here are the key Python best practices...
Sources:
- Python Style Guide (knowledgebase) [85%]
- Clean Code Principles (knowledgebase) [72%]
Confidence: 78%
```
需要在环境中使用 `GOOGLE_API_KEY` 进行查询改进 (Gemini)。
### 直接 Python 用法（可选）
```python
from knowledge_base import search_summaries_tool, knowledge_store_tool
# Search
results = search_summaries_tool("python best practices", limit=5)
# Save
response = knowledge_store_tool(
title="New Knowledge",
content="# Markdown content",
category="knowledgebase"
)
```
---
## 数据库模式
两个表，没有数据重复：
- **documents**：完整内容、元数据、类别（BIGSERIAL 主键）
- **summaries**：自动生成的摘要，带有向量嵌入（BIGSERIAL 主键，引用带有 CASCADE 删除的文档）
有关完整的模式，请参见 [schema.sql](schema.sql)。
---
## Python API 参考
**search_summaries_tool(query, category=None, limit=5, min_relevance=None)**
- 返回：带有结果列表的 SummarySearchResponse
- 每个结果：document_id、title、summary、relevance_score
- 可选的 min_relevance 过滤器 (0.0-1.0)
**fetch_document_tool(document_id)**
- 返回：带有完整内容、元数据的 DocumentResponse
**knowledge_store_tool(title, content, category, tags=None, description=None)**
- 返回：带有 document_id 的 OperationResponse
- 异步：文件写入和摘要生成在后台进行
**update_document_tool(document_id, content)**
- 返回：带有更新的文档元数据的 OperationResponse
- 仅更新内容（标题/类别不变）
- 异步：文件更新和摘要重新生成在后台进行
**delete_document_tool(document_id)**
- 返回：带有已删除文档信息的 OperationResponse
- 永久操作（无法撤消）
- 异步：文件清理在后台进行
**knowledge_list_categories()**
- 返回：带有所有类别和计数的 CategoriesResponse
