knowledgeforge

知识锻造

通用RAG知识系统——AI智能体的共享大脑

KnowledgeForge将您的黑曜石库、项目代码库和代理生成的发现整合到一个统一的可搜索知识库中。它通过MCP（对于Claude Code）和RESTneneneba API（对于任何代理）公开访问。

特性

• 黑曜石保险库索引 --完整的frontmatter、wiki链接、嵌入和标题感知组块
• AST感知代码解析 --基于树的Python、JavaScript、TypeScript、Rust、Go、C/C++、Bash解析
• 发现系统 --人工智能代理存储的见解得到确认并推广回黑曜石
• 多代理访问 -用于Claude Code的MCP服务器+用于Gemini、Codex和其他的REST API
• 共享MCP模式 --一个始终在线的MCP服务器可以通过以下方式在多个客户端之间共享 mcp-remote
• 增量更新 --SHA256基于哈希的更改检测，只重新索引更改的内容
• 实时同步 --具有去抖动重新摄取功能的文件系统监视器
• 本地和私人 --一切都在本地运行，不需要外部服务

建筑

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ Claude Code  │   │   Gemini    │   │    Codex    │
│  (MCP)       │   │  (REST)     │   │  (REST)     │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                   │
       ▼                  ▼                   ▼
┌──────────────────────────────────────────────────────┐
│              KnowledgeForge Engine                     │
│                                                        │
│ MCP (stdio/http) ←→ Core Engine ←→ REST API (8742)    │
│ Shared MCP endpoint (optional): http://127.0.0.1:8743/mcp │
│                     │                                  │
│         ┌───────────┼───────────┐                      │
│         ▼           ▼           ▼                      │
│    [documents]  [codebase]  [discoveries]              │
│                                                        │
│              ChromaDB (embedded)                       │
└──────────────────────────────────────────────────────┘

快速开始

安装

git clone https://github.com/invidtiv/knowledgeforge.git
cd knowledgeforge
pip install -e .
pip install --index-url https://download.pytorch.org/whl/cpu torch

sentence-transformers 拉 torch；在无GPU的服务器上，从CPU轮索引安装，以避免不必要地加载CUDA运行时包。

配置

knowledgeforge config init
# Edit ~/.config/knowledgeforge/config.yaml

设置黑曜石保管库路径和代码项目路径：

obsidian_vault_path: ~/Documents/MyVault
project_paths:
  - path: ~/projects/my-app
    name: my-app

索引您的知识

knowledgeforge index vault              # Index Obsidian vault
knowledgeforge index project ~/myapp    # Index a code project
knowledgeforge index all                # Index everything

启动服务

knowledgeforge serve                    # REST API on port 8742
knowledgeforge watch                    # Live filesystem sync

推荐的持久服务（systemd用户单元）：

systemctl --user enable --now knowledgeforge-api.service
systemctl --user enable --now knowledgeforge-watcher.service
systemctl --user enable --now knowledgeforge-mcp.service
systemctl --user enable --now knowledgeforge-mcp-watchdog.timer

搜索

knowledgeforge search "authentication flow"
knowledgeforge search "database pooling" --project my-app --collection code

摄入和结块

KnowledgeForge将数据视为块（而不是每个文件一条巨大的记录）。

• 黑曜石降价：首先按标题部分拆分；超大部分按重叠的令牌计数进行分割。
• 对话：默认情况下，每个区块一次交换；超大规模的交易所按代币数量进行划分，但存在重叠。
• 代码（树形图）：在结构上分为模块摘要、类/函数/方法块。
• 启发式代码/配置解析：根据文件类型，按SQL语句、空行部分或标记块进行拆分。

分块控制配置在 config.yaml 与：

• max_chunk_size
• chunk_overlap

重要提示：树型符号块（例如，一个非常大的函数体）保持原子性，今天不会进行令牌分割。

MCP集成（克劳德代码）

选项A：直接stdio（简单，每个客户端进程）

添加到您的 .mcp.json:

{
    "mcpServers": {
        "knowledgeforge": {
            "command": "/home/bsdev/knowledgeforge/.venv/bin/python",
            "args": ["-m", "knowledgeforge.interfaces.mcp_server"],
            "env": {
                "KNOWLEDGEFORGE_CONFIG": "/home/bsdev/.config/knowledgeforge/config.yaml"
            }
        }
    }
}

此模式最容易设置，但每个活动的MCP客户端/会话都可以生成自己的Python进程。

选项B：共享MCP端点（推荐）

运行一个始终在线的MCP服务（HTTP传输），让客户端通过 mcp-remote:

{
    "mcpServers": {
        "knowledgeforge": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "http://127.0.0.1:8743/mcp"]
        }
    }
}

优点：

• 内存中的单重知识锻造MCP进程
• 在多个IDE/代理客户端下具有更好的稳定性
• 使用相同的端点跨Codex、Claude、Gemini和Windsurf工作

可用的MCP工具：

• search_knowledge --搜索文档、代码和发现
• get_knowledge_context --在搜索命中后读取确切的文件行
• store_discovery --存储调试见解和经验
• get_project_context --获取项目概述
• list_projects --列出索引项目
• ingest_path --索引文件或目录
• get_discoveries --检索过去的发现
• search_conversations --搜索过去的Claude/Codex/Gemini对话
• read_conversation --按会话ID读取对话记录

REST API

基本URL: http://127.0.0.1:8742/api/v1

如果客户端在Docker中运行，而KnowledgeForge在主机上运行，请使用： http://host.docker.internal:8742/api/v1

# Search
curl -X POST http://127.0.0.1:8742/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "how does auth work", "project": "my-app"}'

# Store discovery
curl -X POST http://127.0.0.1:8742/api/v1/discoveries \
  -H "Content-Type: application/json" \
  -d '{"content": "Pool exhaustion at 100 connections", "category": "bugfix", "severity": "critical"}'

# List projects
curl http://127.0.0.1:8742/api/v1/projects

# Health check
curl http://127.0.0.1:8742/api/v1/health

看 docs/api-reference.md 获取完整的API文档。

发现工作流程

发现系统在AI代理和您的知识库之间创建了一个反馈循环：

Agent discovers insight → Stored in ChromaDB
     ↓
User reviews via CLI → Confirms or rejects
     ↓
Confirmed → Promoted to Obsidian vault as markdown note
     ↓
Obsidian note → Re-ingested into knowledge base
     ↓
Available to all agents via search

# Interactive review
knowledgeforge discoveries review

# Promote confirmed discoveries to Obsidian
knowledgeforge discoveries promote

技术栈

项目结构

knowledgeforge/
├── src/knowledgeforge/
│   ├── config.py               # Configuration (YAML + env vars)
│   ├── core/
│   │   ├── engine.py           # Main orchestrator
│   │   ├── embedder.py         # Embedding wrapper
│   │   ├── store.py            # ChromaDB wrapper
│   │   └── models.py           # Pydantic data models
│   ├── ingestion/
│   │   ├── obsidian.py         # Obsidian vault parser
│   │   ├── code.py             # tree-sitter code parser
│   │   ├── chunker.py          # Chunking utilities
│   │   └── watcher.py          # Filesystem watcher
│   ├── interfaces/
│   │   ├── mcp_server.py       # MCP server (Claude Code)
│   │   ├── rest_api.py         # REST API (FastAPI)
│   │   └── cli.py              # Admin CLI (Typer)
│   └── discovery/
│       ├── manager.py          # Discovery CRUD
│       └── promoter.py         # Obsidian write-back
├── scripts/
│   ├── setup.sh / setup.ps1    # Installation scripts
│   └── run.sh                  # Service launcher
├── pyproject.toml
└── config.yaml

CLI 参考

knowledgeforge index vault [--full]          # Index Obsidian vault
knowledgeforge index project PATH [--name X] # Index code project
knowledgeforge index all [--full]            # Index everything

knowledgeforge search QUERY [-p PROJECT] [-c COLLECTION] [-n COUNT]

knowledgeforge discoveries list [-p PROJECT] [--unconfirmed] [--category X]
knowledgeforge discoveries review            # Interactive review
knowledgeforge discoveries confirm ID
knowledgeforge discoveries reject ID
knowledgeforge discoveries promote           # Write to Obsidian

knowledgeforge projects                      # List indexed projects
knowledgeforge stats                         # System statistics
knowledgeforge serve [--rest-only|--mcp-only]
knowledgeforge watch                         # Live file sync
knowledgeforge config show|init

需求

• Python 3.10+
• 无需Docker——一切都可以在本地运行

文档

• API 参考 -完整的REST API文档
• 配置指南 -配置选项和示例
• 建筑 -系统设计和数据流
• 操作手册 -服务操作、健康检查和故障排除
• 开发指南 -贡献和开发设置

用例

对于独立开发者

• 索引您的个人黑曜石知识库
• 从任何AI代理搜索您的所有项目
• 存储跨会话持久的调试见解

对于团队

• 跨多个项目共享知识库
• 规范AI代理访问项目上下文的方式
• Discovery系统创建实时文档

用于研究

• 索引黑曜石的学术论文和笔记
• 跨多个研究代码库的代码分析
• 跟踪实验见解和发现

演出

• 增量索引：仅重新处理更改的文件
• 高效分块：语义边界有助于更好地检索
• 本地嵌入：无API调用，即时结果
• 持久存储：ChromaDB在重启过程中保持状态

路线图

• \[\]支持其他文档格式（PDF、DOCX）
• \[\]用于发现管理的Web UI
• \[\]具有访问控制的多用户支持
• \[\]Slack/Discord机器人集成
• \[\]用于关系提取的GraphRAG
• \[\]自定义嵌入模型支持

贡献

欢迎投稿！请看 贡献.md 作为指导方针。

许可证

麻省理工学院

支持

• 问题：https://github.com/tiaz-fr/knowledgeforge/issues
• 讨论：https://github.com/tiaz-fr/knowledgeforge/discussions

______________________________________________________________________

基于对AI代理生态系统的热爱而构建。由开发者构建，为开发者服务。