AuroraKB

AuroraKB是一个基于语义搜索的知识库系统，通过MCP（模型上下文协议）为AI助手提供持久的上下文存储。

特性

令牌优化（两阶段检索）：将代币消耗量减少约90%

- 默认情况下返回简短摘要，而不是完整内容 - 代理人审查摘要以确定相关性 - 通过按需获取完整内容 aurora_retrieve(document_id) - 摄取时自动摘要（零搜索延迟） - 向后兼容 include_full_content 参数

混合搜索：结合语义（70%）+关键字（30%）搜索，以获得更高的准确性

- 通过向量嵌入进行语义理解 - 位置感知关键字与PostgreSQL ts_rank_cd匹配 - 针对“第二阶段计划”等短查询的自动查询优化

代理驱动的查询扩展：代理可以使用同义词扩展查询，以便更好地回忆

- 无需额外的LLM成本-代理可以通过完全的上下文感知自行扩展查询 - 可选的基于LLM的扩展可用，但默认情况下已禁用

项目感知上下文：自动检测相同的项目内容并确定其优先级
智能搜索提升：相同的项目结果获得+0.15的相似性提升，以获得更好的相关性
灵活的命名空间：按项目或域隔离数据
元数据筛选：按文档类型、作者、标签等筛选
纯MCP架构：无需HTTP中间件的直接数据库连接-简单高效
多代理友好：每个AI代理独立运行，没有端口冲突
即插即用：只需配置MCP配置文件，就可以开始了

需求

Python 3.12+
PostgreSQL 17+，带pgvector扩展
OpenAI API密钥（用于生成嵌入）

安装

1.克隆存储库

git clone https://github.com/yourusername/AuroraKB
cd AuroraKB

2.安装依赖项

使用 uv 对于依赖关系管理（推荐）：

uv sync

或者使用pip：

pip install -r requirements.txt

3.设置PostgreSQL数据库

Docker快速入门（推荐）：

docker run -d \
  --name aurora_kb_postgres \
  -e POSTGRES_DB=aurora_kb \
  -e POSTGRES_USER=aurora_user \
  -e POSTGRES_PASSWORD=aurora_pass \
  -p 5432:5432 \
  pgvector/pgvector:pg17

运行数据库迁移：

uv run python scripts/setup_db.py

4.配置克劳德代码MCP

将以下配置添加到您的Claude Code MCP配置文件中：

配置文件位置:

克劳德桌面： ~/.config/claude/claude_desktop_config.json
克劳德代码： ~/.claude.json

推荐配置：

{
  "mcpServers": {
    "aurora_kb": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/AuroraKB", "run", "python", "-m", "aurora_mcp.server"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://aurora_user:aurora_pass@localhost:5432/aurora_kb",
        "OPENAI_API_KEY": "sk-your-openai-api-key-here",
        "OPENAI_BASE_URL": "https://api.openai.com/v1",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_DIMENSION": "1536"
      }
    }
  }
}

重要说明:

替换 /absolute/path/to/AuroraKB 与项目的实际绝对路径
替换 sk-your-openai-api-key-here 使用您的OpenAI API密钥
要使用其他嵌入服务，请修改 OPENAI_BASE_URL 到相应的API端点

5.启动克劳德代码

重新启动Claude Code或重新加载MCP配置，AuroraKB将自动启动！

用法

储存内容（摄入）

通过Claude Code聊天使用MCP工具：

Please store this content in AuroraKB:
"Today we discussed the project architecture and decided to use FastAPI + PostgreSQL + pgvector"

Parameters:
- namespace: my_project
- document_type: conversation
- source: claude_chat

语义搜索

Search AuroraKB for discussions about "project architecture"

检索文档

Retrieve document with document_id "doc_123" from AuroraKB

处理长文档

AuroraKB对每个存储操作有内容长度限制（约8000个令牌/约32000个字符）。对于较长的文档，请使用以下策略之一：

策略1：分块存储（建议用于技术文件）

Please split this long document into chunks and store in AuroraKB:

[Long document content...]

Requirements:
1. Each chunk should not exceed 6000 tokens
2. Maintain 200 character overlap between chunks for context continuity
3. Use metadata to link all chunks:
   - parent_id: Generate a unique ID
   - chunk_index: Chunk sequence number (0, 1, 2...)
   - total_chunks: Total number of chunks
4. namespace: my_project
5. document_type: document

策略2：摘要存储（建议用于对话记录）

Please summarize the key content of this long conversation and store in AuroraKB:

[Long conversation content...]

Requirements:
1. Extract key decisions, discussion points, and conclusions
2. Preserve original semantics and important details
3. Storage parameters:
   - namespace: my_project
   - document_type: conversation
   - metadata: {"summary": true, "original_length": "original character count"}

策略3：选择性存储（建议用于混合内容）

Please extract the most relevant parts from this long document and store in AuroraKB:

[Long document content...]

Focus on: [Describe the topics you care about]

Requirements:
- Only store paragraphs relevant to the topic
- namespace: my_project
- document_type: document

MCP工具参考

极光孕育

通过自动语义向量生成和项目检测将内容存储到AuroraKB中。

参数:

content （必填）：要存储的文本内容

- 最大长度：~8000个令牌（~32000个字符） - 超出限制时返回错误和建议

document_type （必填）：文档类型-必须是以下之一：

- document：一般文件 - conversation：对话记录 - decision：决策记录 - resolution：决议/解决方案 - report：报告文件

title （必填）：简要标题或描述

- 用于搜索结果显示（两阶段检索优化） - 应简洁（1-2句话）和描述性 - 代理商最了解内容，因此代理商提供的标题最准确

namespace （可选）：用于项目隔离的命名空间（默认值：“default”）
source （可选）：源/角色标识符（例如，“qc”、“后端”、“前端”）

- 如果未提供，则使用环境变量中的AURORA_AGENT_ID - 如果未配置，则返回“未知”

metadata （可选）：附加元数据对象

- author：作者姓名 - tags：标签数组 - url：关联的URL - parent_id：用于链接分块文档 - chunk_index：分块序列号（用于分块存储） - total_chunks：块总数（用于分块存储）

working_directory （可选，推荐）：当前工作目录路径

- 用于自动检测项目根以进行项目感知搜索 - 在此处传递您的cwd以进行自动项目关联

项目检测: 当 working_directory 提供后，AuroraKB会通过查找以下标记自动检测项目根 .git, package.json, pyproject.toml等等。检测到 project_path 与文档一起存储并在响应中返回。

极光搜索

基于语义相似性搜索内容，并可选择项目感知增强。

搜索提示: 为了更好地回忆，请考虑在调用之前向查询中添加同义词或相关术语。例子： "Phase 4 plan" → "Phase 4 plan execution implementation 执行计划"

参数:

query （必填）：搜索查询文本

- 为了更好地回忆，请包括同义词或相关术语

namespace （可选）：限制到特定命名空间
document_type （可选）：按文档类型筛选
limit （可选）：要返回的结果数，默认值为10
threshold （可选）：相似性阈值（0.0-1.0），默认值0.2
metadata_filters （可选）：元数据筛选器

- author：按作者筛选 - tags：按标签筛选 - source：按来源筛选

current_project_path （可选）：提升相同项目成果的当前项目路径
expand_query （可选）：使用LLM自动展开查询（默认值：False）

- 通常是不必要的，因为您可以通过更好的上下文感知自己扩展查询

rerank （可选）：通过LLM重新排列结果（默认值：False）

- 通常是不必要的，因为使用数学评分的混合搜索更可靠

项目感知搜索: 当 current_project_path 如果提供，来自同一项目的文档将获得+0.15的相似性提升（上限为1.0），使其在搜索结果中排名更高。这有助于优先考虑当前项目中的相关上下文，同时仍然允许在需要时进行跨项目搜索。

响应字段:

documents：匹配文档数组

- project_path：检测到的项目路径（如果可用） - is_same_project：布尔标志，指示文档是否来自当前项目 - similarity_score：相似性得分（如果是同一项目，则提高）

current_project：current_project_path参数的回声
total_found：返回的结果数

极光再现

通过document_id检索特定文档。

参数:

document_id （必填）：文档ID
include_embedding （可选）：是否包含矢量数据，默认为false

aurora_update

更新AuroraKB中的现有文档。

参数:

document_id （必填）：唯一文档标识符
content （可选）：新内容（如果提供，将重新生成嵌入）
metadata （可选）：新元数据（将与现有元数据合并）
document_type （可选）：新文档类型

行为:

当 content 更新后，嵌入向量会自动重新生成
当 metadata 更新后，它将与现有元数据合并（不替换）
返回已更新字段和新字段的列表 updated_at 时间戳

示例:

# Update metadata only
aurora_update(
    document_id="abc-123",
    metadata={"status": "reviewed", "version": "2"}
)

# Update content (regenerates embedding)
aurora_update(
    document_id="abc-123",
    content="Updated content here"
)

极光

从AuroraKB中删除文档。

参数:

document_id （必填）：唯一文档标识符

行为:

永久删除文档（无法撤消）
返回包含已删除文档信息的删除确认

示例:

aurora_delete(document_id="abc-123")

极光列表

使用结构化筛选列出AuroraKB中的文档。

参数:

namespace （可选）：按命名空间筛选
document_type （可选）：按文档类型筛选
source （可选）：按来源筛选
project_path （可选）：按项目路径筛选
limit （可选）：最大结果数（默认值：20，最大值：100）
offset （可选）：分页时要跳过的结果数（默认值：0）

行为:

返回简要文档信息（id、标题、预览）
所有字符串过滤器都不区分大小写
结果按created_at排序（最新者优先）
支持带限制和偏移的分页

示例:

# List all documents in ariadne namespace
aurora_list(namespace="ariadne", limit=10)

# List all decision documents
aurora_list(document_type="decision")

# Combine filters
aurora_list(namespace="ariadne", document_type="decision", source="qc")

# Pagination
aurora_list(namespace="ariadne", limit=20, offset=20)

高级配置

使用自定义嵌入服务

AuroraKB支持任何与OpenAI API兼容的嵌入服务：

{
  "env": {
    "OPENAI_BASE_URL": "https://your-custom-endpoint.com/v1",
    "OPENAI_API_KEY": "your-api-key",
    "EMBEDDING_MODEL": "custom-embedding-model"
  }
}

启用查询扩展（可选，通常不必要）

查询扩展使用LLM自动扩展具有相关术语的搜索查询。然而，这是 默认禁用 因为：

AI代理（Claude、GPT、Gemini）可以通过完全的上下文感知自行扩展查询
代理驱动的扩展是免费的，更准确
基于LLM的扩展增加了延迟和成本

如果仍要启用基于LLM的扩展：

{
  "env": {
    "QUERY_EXPANSION_MODEL": "deepseek-ai/DeepSeek-V3",
    "QUERY_EXPANSION_BASE_URL": "https://api.siliconflow.cn/v1",
    "QUERY_EXPANSION_API_KEY": "sk-your-api-key",
    "QUERY_EXPANSION_TEMPERATURE": "0.3",
    "QUERY_EXPANSION_MAX_TOKENS": "50"
  }
}

然后打电话 aurora_search 随着 expand_query=True 以启用它。

启用令牌优化（推荐）

令牌优化使用LLM在摄取时自动生成简短摘要，将搜索结果令牌消耗减少约90%。要启用：

{
  "env": {
    "SUMMARIZATION_MODEL": "deepseek-ai/DeepSeek-V3",
    "SUMMARIZATION_BASE_URL": "https://api.siliconflow.cn/v1",
    "SUMMARIZATION_API_KEY": "sk-your-api-key",
    "SUMMARIZATION_TEMPERATURE": "0.3",
    "SUMMARIZATION_MAX_TOKENS": "150"
  }
}

配置说明:

当满足以下条件时，会自动启用摘要 SUMMARIZATION_MODEL 已配置
智能回退链:

1. 用途 SUMMARIZATION_BASE_URL 和 SUMMARIZATION_API_KEY 如果提供 1. 回落到 QUERY_EXPANSION_BASE_URL 和 QUERY_EXPANSION_API_KEY （两者都是LLM任务） 1. 最后回到 OPENAI_BASE_URL 和 OPENAI_API_KEY

摘要在摄取时生成（给摄取增加了约300ms的延迟）
搜索默认返回摘要；使用 include_full_content=True 为了向后兼容性
摘要将缓存1小时，以避免重复总结相同的内容

回填现有文件:

启用摘要后，为现有文档生成摘要：

# Dry run to preview
uv run python scripts/backfill_summaries.py --dry-run

# Process all documents (10 docs/batch, 6s delay)
uv run python scripts/backfill_summaries.py

# Custom batch size and delay
uv run python scripts/backfill_summaries.py --batch-size 5 --delay 10

# Process specific namespace only
uv run python scripts/backfill_summaries.py --namespace my_project

开发指南

运行单元测试

uv run pytest tests/

运行MCP服务器（开发模式）

uv run python -m aurora_mcp.server

建筑

┌─────────────────────┐
│   Claude Code       │
│   (MCP Client)      │
└──────────┬──────────┘
           │ stdio
           ▼
┌─────────────────────┐
│   MCP Server        │
│ (aurora_mcp.server) │
└──────────┬──────────┘
           │ direct connection
           ▼
┌─────────────────────┐
│  PostgreSQL         │
│  + pgvector         │
└─────────────────────┘

纯MCP设计:

无需HTTP中间件的直接数据库连接
无需手动流程管理
简化配置，提高可用性

故障排除

数据库连接失败

验证PostgreSQL是否正在运行：

docker ps | grep aurora_kb_postgres

测试数据库连接：

psql postgresql://aurora_user:aurora_pass@localhost:5432/aurora_kb

嵌入生成失败

检查OpenAI API密钥是否有效：

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

搜索优化状态

AuroraKB已经完成了一项全面的搜索优化计划：

✅ 第一阶段：混合搜索（已完成）

状态：生产就绪
特性:

- 将语义搜索（70%）与PostgreSQL全文搜索（30%）相结合 - 使用ts_rank_cd进行位置感知关键字排名 - 用于高效全文搜索的GIN索引 - 短查询的自动查询优化

影响：显著提高了搜索准确性，特别是对于关键字较多的查询

✅ 第2阶段：查询扩展（已完成，默认禁用）

状态：生产就绪，但默认禁用
改变：经过测试，我们发现AI代理（Claude、GPT、Gemini）可以通过更好的上下文感知自行扩展查询
特性:

- 基于LLM的查询扩展，包含相关术语（可选） - 智能缓存（1小时TTL），以减少延迟和成本 - 可与任何兼容OpenAI的API一起配置

推荐：让代理自行扩展查询，而不是使用基于LLM的扩展

- 代理具有完整的对话上下文 - 代理可以根据搜索结果进行调整 - 零额外成本

❌ 第三阶段：法学硕士重新排名（已弃用）

状态：已实现，但默认情况下已禁用
理由：测试显示，基于LLM的重新排名引入了降低准确性的偏差：

- 长度偏差：法学硕士更喜欢更长、更“全面”的文档，而不是重点突出的文档 - 语义混乱：LLM可能会混淆类似的概念（例如，“实施时间表”与“执行计划”） - 信息过载：处理20+个文档，每个文档包含600+个字符，会降低判断质量

结论：结合数学评分（嵌入+关键字）的混合搜索比主观LLM判断更可靠
未来：如果需要，可以使用专门的重新评级模型（Cohere Rerank、Jina Reranker）进行重新评估

当前建议：使用混合搜索以获得最佳结果。默认情况下，查询扩展和重新排名都是禁用的——代理可以通过更好的上下文感知来扩展查询本身，并且具有数学评分的混合搜索比LLM主观判断更可靠。

许可证

MIT许可证

贡献

欢迎问题和拉取请求！

Aurora (Eonchpy)

快速接入

详细介绍