内容
# Archivist
领域驱动的 **MCP 服务器** （STDIO），在称为 **第二大脑** 的个人知识库上提供稳定的检索能力。Archivist 返回带有出处证明；您的代理负责推理。
Archivist 构建用于读取遵循 **第二大脑** 领域模型的知识库——特别是公共参考库 [alcantaraleo/second-brain-public](https://github.com/alcantaraleo/second-brain-public)。克隆该仓库（或使用您自己的兼容树）并将 `ARCHIVIST_SECOND_BRAIN_PATH` 指向其根目录。
## 快速入门
**前提条件：** Java 21+，Gradle 包装器（已包含），用作知识库根目录的目录。
```bash
git clone https://github.com/alcantaraleo/archivist.git
cd archivist
./gradlew :transport:bootJar
export ARCHIVIST_SECOND_BRAIN_PATH=/path/to/your/corpus # 必须存在
java -jar transport/build/libs/transport.jar # MCP 输出到 stdout；日志输出到 stderr
```
尝试使用已检查的固定装置（fixture）而无需个人知识库：
```bash
export ARCHIVIST_SECOND_BRAIN_PATH="$(pwd)/infrastructure/src/test/resources/fixture-corpus"
./gradlew :transport:bootRun
```
或使用公共参考第二大脑（与 Archivist 目标相同的布局）：
```bash
git clone https://github.com/alcantaraleo/second-brain-public.git /path/to/second-brain-public
export ARCHIVIST_SECOND_BRAIN_PATH=/path/to/second-brain-public
./gradlew :transport:bootRun
```
将您的代理连接到 jar 文件 - 请参阅 [代理 MCP 配置](#agent-mcp-configuration)。
## 目录
- [概述](#overview)
- [MCP 工具和响应](#mcp-tools-and-responses)
- [知识库要求](#corpus-requirements)
- [入门](#getting-started)
- [配置](#configuration)
- [架构](#architecture)
- [开发](#development)
- [路线图](#roadmap)
- [文档](#documentation)
- [许可证](#license)
## 概述
Archivist 是 **LLM 代理** 和知识库之间的 **检索层**。公共接口使用 **领域术语** （`findDecisions`、`findPeople` 等）。存储、索引和排名策略保持 **私有**，并且可以在不破坏 MCP 客户端的情况下演变（目前为词汇检索；路线图上有混合和图谱检索）。
它位于外部 LLM 代理和个人知识系统之间，暴露领域特定的能力，以便代理检索知识，而无需知道知识如何存储、索引或组织。
```
┌──────────────────────────────────────────────────────────────────┐
│ 使用代理（推理） │
│ Cursor · Claude · GPT · 自定义代理 · CLI │
└───────────────────────────────┬──────────────────────────────────┘
│
MCP / 未来的 REST · CLI
仅限领域能力
（证据 + 来源 - 不是答案）
│
┌───────────────────────────────▼──────────────────────────────────┐
│ Archivist │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 传输（当前为 MCP）→ 应用程序 → 领域接口 │ │
│ └──────────────────────────────┬─────────────────────────────┘ │
│ │ 私有 │
│ ┌──────────────────────────────▼─────────────────────────────┐ │
│ │ 基础设施：检索策略 · 第二大脑适配器 │ │
│ └────────────────────────────────────────────────────────────┘ │
└───────────────────────────────┬──────────────────────────────────┘
│ 只读知识库访问
┌───────────────────────────────▼──────────────────────────────────┐
│ 第二大脑（您的知识库） │
│ Markdown 条目 · 分区 · 类型 · 来源链 │
│ 存储布局和索引是实现细节 │
└──────────────────────────────────────────────────────────────────┘
```
### Archivist 是什么
- 八个稳定 **功能** 的 MCP 适配器
- 只读访问 Markdown 知识条目及其元数据
- 证据 + **来源证明** （来源 ID、类型、分区、标签、来源链、时间戳）
### Archivist 不是什么
- 不是文件系统包装器、Markdown 全文搜索 UI 或 RAG 答案引擎
- 不是代理、摘要器或推理引擎
- 不是托管服务 - 它在您的 **知识库路径** 上本地运行
**边界：** Archivist 检索证据。消费代理合成、解释并回答。
## MCP 工具和响应
**服务器标识：** `archivist` （MCP 服务器名称）。版本在 `transport/src/main/resources/application.properties` 中设置（Release Please 与 GitHub 版本保持同步）。
**传输：** 通过 **STDIO** 进行 MCP。启动确认和错误输出到 **stderr**；**stdout** 保留用于 MCP 协议。
### 工具
| 工具 | 参数 | 目的 |
| ---- | --------- | ------- |
| `retrieveContext` | `query` | 跨所有分区的上下文检索 |
| `findDecisions` | `topic` | 架构和产品决策（ADRs） |
| `findProjects` | `criteria` | 项目和计划 |
| `findPeople` | `name` | 具有专业背景的人员 |
| `findConcepts` | `topic` | 概念和交叉见解 |
| `findRelatedKnowledge` | `query` | 相关知识（参见下面的 [当前行为](#roadmap)） |
| `findReadings` | `topic` | 源材料（文章、记录、笔记） |
| `findDebriefs` | `topic` | 事件回顾和学习评审 |
规范工具名称和 JSON 模式：[`specs/002-mcp-transport-adapter/contracts/mcp-tools-expected.json`](specs/002-mcp-transport-adapter/contracts/mcp-tools-expected.json)。
### 响应形状
每个工具返回一个 JSON 数组 **证据** 对象：
```json
[
{
"content": "检索到的正文文本（如果可用）",
"provenance": {
"sourceId": "稳定的条目 ID",
"title": "人类可读的标题",
"type": "CONCEPT",
"zone": "SYNTHESIZED",
"tags": ["tag-one"],
"sources": ["上游源 ID"],
"created": "2026-01-01T12:00:00Z",
"updated": "2026-01-02T12:00:00Z"
}
}
]
```
示例固定装置：[`specs/002-mcp-transport-adapter/contracts/evidence-response-schema-expected.json`](specs/002-mcp-transport-adapter/contracts/evidence-response-schema-expected.json)。如果条目超过大小限制，条目可能省略正文 `content`; 来源仍然描述条目（`contentAvailability` 在领域模型中）。
**当前检索：** 所有工具都使用词汇策略，默认情况下每个调用最多返回 **20** 个结果。根据适用情况，类型和分区感知能力过滤到相关的 `KnowledgeType`。
## 知识库要求
Archivist **不** 携带知识库。你将 `ARCHIVIST_SECOND_BRAIN_PATH` 指向磁盘上的 **现有目录**。
**参考知识库：** [github.com/alcantaraleo/second-brain-public](https://github.com/alcantaraleo/second-brain-public) - 公共第二大脑保险库（LLM-Wiki 样式布局），该项目旨在从中检索。使用它来端到端测试 Archivist 或作为您自己的知识库模板。
### 格式（当前实现）
- 知识库根目录下的 **Markdown** 文件（只读扫描）
- **YAML 前置元数据** 用于元数据（`type`，可选 `zone`，标签，日期，`sources` 等）
- 没有识别的 `type`（和没有配置的别名）的条目将被跳过
领域模型定义在 [`docs/second-brain-domain.md`](docs/second-brain-domain.md)。 [second-brain-public](https://github.com/alcantaraleo/second-brain-public) 仓库是该模型在磁盘上的主要公共示例。许多用户在 **Obsidian 保险库** 中保存知识库，并具有相同的目录布局；Archivist 的 **公共接口** 不依赖于 Obsidian - 只有基础设施适配器将文件映射到领域类型和分区。
### 默认分区映射（路径前缀）
相对于知识库根目录，最长的匹配前缀获胜（不区分大小写）：
| 前缀 | 领域分区 |
| ------ | ----------- |
| `raw/` | `SOURCE` |
| `wiki/` | `SYNTHESIZED` |
| `dev/` | `TECHNICAL` |
| `identity/` | `IDENTITY` |
| `runtime/` | `COMPILED` |
| `observability/` | `SIGNAL` |
前置元数据 `zone` 在有效时覆盖路径推断。详细信息和类型别名（例如 `meeting-person` → `PERSON`）：[`specs/003-second-brain-integration/contracts/mapping-defaults.md`](specs/003-second-brain-integration/contracts/mapping-defaults.md)。
通过 Spring 配置覆盖映射（`archivist.second-brain.mapping.*`）- 参见 [配置](#configuration)。
### 隐私
服务器读取您配置的路径。 将 MCP 配置和环境变量保持在公共存储库之外，如果它们包含个人路径。 Archivist 不会上传您的知识库。
## 入门
### 前提条件
- Java 21+
- **现有** 的知识库根目录
### 构建
```bash
./gradlew build
```
MCP 胖 jar（稳定路径 - 版本更新不会重命名文件）：
```text
transport/build/libs/transport.jar
```
仅构建 jar：
```bash
./gradlew :transport:bootJar
```
### 运行（STDIO MCP 服务器）
```bash
export ARCHIVIST_SECOND_BRAIN_PATH=/path/to/existing/directory
./gradlew :transport:bootRun
```
或者直接运行 jar（在 `bootJar` 之后）：
```bash
export ARCHIVIST_SECOND_BRAIN_PATH=/path/to/existing/directory
java -jar transport/build/libs/transport.jar
```
如果变量丢失、为空或不是现有目录，则进程 **在启动时失败**，并显示一条消息，说明 `archivist.second-brain.path` 和 `ARCHIVIST_SECOND_BRAIN_PATH`。
### 代理 MCP 配置
将工具链指向稳定的 jar 文件路径。在拉取更改后重建。
```json
{
"mcpServers": {
"archivist": {
"command": "java",
"args": ["-jar", "/absolute/path/to/archivist/transport/build/libs/transport.jar"],
"env": {
"ARCHIVIST_SECOND_BRAIN_PATH": "/absolute/path/to/corpus"
}
}
}
}
```
与 Cursor、Claude Desktop 和其他 MCP STDIO 客户端配合使用 - 调整您的工具配置文件位置。
## 配置
环境特定的值使用 **环境变量** 和 Spring Boot 外部配置。默认值位于 [`transport/src/main/resources/application.properties`](transport/src/main/resources/application.properties)。
| 变量 | 必需 | 描述 |
| -------- | -------- | ----------- |
| `ARCHIVIST_SECOND_BRAIN_PATH` | **是** | 指向现有知识库根目录的绝对路径 |
| `ARCHIVIST_RETRIEVAL_ACTIVE_STRATEGY` | 否 | 活动检索策略：`lexical`（默认）、`bm25` 或 `embedding` |
| `ARCHIVIST_RETRIEVAL_MAX_RESULTS` | 否 | 每个功能调用的最大证据项（默认：`20`） |
完整的嵌入和 BM25 属性列表：[`specs/006-embedding-retrieval/contracts/embedding-configuration.md`](specs/006-embedding-retrieval/contracts/embedding-configuration.md) 和 [`specs/005-bm25-retrieval/contracts/bm25-configuration.md`](specs/005-bm25-retrieval/contracts/bm25-configuration.md)。验证演练：[`specs/006-embedding-retrieval/quickstart.md`](specs/006-embedding-retrieval/quickstart.md)。
### 嵌入式检索（可选）
使用 **`ARCHIVIST_RETRIEVAL_ACTIVE_STRATEGY=embedding`** 启用语义排名。向量索引当前版本仅使用内存存储（`ARCHIVIST_RETRIEVAL_EMBEDDING_STORE=memory`）。
| 嵌入 ID | 它是什么 |
| ------------- | ---------- |
| `local` | Archivist JVM 中的 ONNX 模型（默认情况下为 `embedding` 策略；第一次运行可能会下载权重）。与 `dimensions=384` 一起使用，除非您覆盖模型。 |
| `openai-compatible` | HTTP **`POST {base-url}/v1/embeddings`** （OpenAI JSON 形状）。**相同的适配器** 用于 [OpenAI](https://platform.openai.com/) 和 **本地代理** （文本嵌入推理、Ollama OpenAI 仿真器等）- 仅 `base-url`、`model`、`api-key` 和 **`dimensions`** 更改。 |
| `stub` | 用于测试的确定性离线向量；不用于生产。 |
**OpenAI-compatible: 两个操作路径（一个嵌入 ID）|
| 目标 | `ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_BASE_URL` | 典型的 `…_OPENAI_MODEL` | 典型的 `ARCHIVIST_RETRIEVAL_EMBEDDING_DIMENSIONS` |
| ------ | ------------------------------------------------- | -------------------------- | -------------------------------------------------- |
| OpenAI API | `https://api.openai.com` | `text-embedding-3-small` | `1536` |
| 本地 OpenAI 形状服务器 | `http://localhost:<port>` （例如 Docker Compose 示例在 `8080` 上） | 服务器的模型 ID（例如 `sentence-transformers/all-MiniLM-L6-v2`） | 必须与该模型匹配（通常为 `384`） |
Spring Boot **不** 自动读取 `OPENAI_API_KEY`。对于 MCP/`bootRun`，设置 **`ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_API_KEY`** （例如 `export ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_API_KEY="$OPENAI_API_KEY"`）。
OpenAI 示例（在 `export ARCHIVIST_SECOND_BRAIN_PATH=…` 之后）：
```bash
export ARCHIVIST_RETRIEVAL_ACTIVE_STRATEGY=embedding
export ARCHIVIST_RETRIEVAL_EMBEDDING_EMBEDDER=openai-compatible
export ARCHIVIST_RETRIEVAL_EMBEDDING_STORE=memory
export ARCHIVIST_RETRIEVAL_EMBEDDING_DIMENSIONS=1536
export ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_BASE_URL=https://api.openai.com
export ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_API_KEY="$OPENAI_API_KEY"
export ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_MODEL=text-embedding-3-small
./gradlew :transport:bootRun
```
示例 - **本地 OpenAI 兼容端点** （TEI 或类似；参见 [`deploy/docker-compose.embedding.example.yml`](deploy/docker-compose.embedding.example.yml)）：
```bash
export ARCHIVIST_RETRIEVAL_ACTIVE_STRATEGY=embedding
export ARCHIVIST_RETRIEVAL_EMBEDDING_EMBEDDER=openai-compatible
export ARCHIVIST_RETRIEVAL_EMBEDDING_STORE=memory
export ARCHIVIST_RETRIEVAL_EMBEDDING_DIMENSIONS=384
export ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_BASE_URL=http://localhost:8080
export ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_MODEL=sentence-transformers/all-MiniLM-L6-v2
export ARCHIVIST_RETRIEVAL_EMBEDDING_OPENAI_API_KEY=""
./gradlew :transport:bootRun
```
示例 - **进程内本地 ONNX** （无需 HTTP 嵌入服务器）：
```bash
export ARCHIVIST_RETRIEVAL_ACTIVE_STRATEGY=embedding
export ARCHIVIST_RETRIEVAL_EMBEDDING_EMBEDDER=local
export ARCHIVIST_RETRIEVAL_EMBEDDING_STORE=memory
export ARCHIVIST_RETRIEVAL_EMBEDDING_DIMENSIONS=384
./gradlew :transport:bootRun
```
不匹配的 **`dimensions`** （属性与模型返回的向量）会在启动时或索引构建时失败，并显示明确的错误。
附加知识库调优（可选，Spring 属性名称）：
| 属性 | 默认值 | 目的 |
| -------- | ------- | ------- |
| `archivist.second-brain.max-entry-bytes` | `1048576` | 跳过加载超大正文；保留来源证明 |
| `archivist.second-brain.ignore-globs` | `**/templates/**`, `**/.trash/**` | 发现时排除的路径 |
分区/类型映射：`archivist.second-brain.mapping.zone-prefixes`, `archivist.second-brain.mapping.type-aliases`。 参见 [`SecondBrainMappingProperties`](infrastructure/src/main/java/io/archivist/infrastructure/secondbrain/SecondBrainMappingProperties.java) 获取默认值。
## 架构
```
┌───────────────────────────────────────────────────────────────────┐
│ 外部消费者 │
│ （LLM 代理、Claude、GPT、CLI、测试） │
└──────────────────────────────┬────────────────────────────────────┘
│
┌───────────────▼───────────────┐
│ 传输层 │
│ MCP 服务器 │ REST │ CLI │
└───────────────┬───────────────┘
│ 仅限领域能力
┌───────────────▼───────────────┐
│ 应用程序层 │
│ 用例 / 交互器 │
└──────┬────────────────┬────────┘
│ │
┌───────────▼──────┐ ┌──────▼──────────────────┐
│ 领域层 │ │ 基础设施层 │
│ │ │ │
│ · 实体 │ │ · 检索策略 │
│ · 端口 In │ │ · 第二大脑适配器 │
│ · 端口 Out │ │ · 嵌入式提供程序 │
│ · 领域规则 │ │ · 向量存储 │
└──────────────────┘ └──────────────────────────┘
```
**依赖规则：** 所有箭头指向内部。领域层不知道 Spring、MCP、Spring AI 或任何存储技术。基础设施层实现了领域定义的接口。完整的变量和层规则：[`AGENTS.md`](AGENTS.md)。
### 包布局
```
io.archivist
├── domain/model, domain/port/in, domain/port/out
├── application/usecase
├── infrastructure/retrieval, infrastructure/secondbrain
└── transport/mcp
```
### 技术栈
| 关注点 | 技术 |
| ------- | ---------- |
| 语言 | Java 21+ |
| 框架 | Spring Boot 4.1.0 |
| AI / MCP | Spring AI 2.0.0（MCP 服务器，STDIO） |
| 构建 | Gradle（Kotlin DSL） |
| 测试 | JUnit 5、Mockito |
## 开发
### 本地验证
```bash
./gradlew build
```
运行领域、应用程序、基础设施和传输测试（包括 MCP 合同回归测试和固定装置测试）。
拉取请求和推送到 `main` 运行相同的 `./gradlew build` 操作，在 [`.github/workflows/ci.yml`](.github/workflows/ci.yml) 中（Java 21）。
### 规范驱动的工作流
重要的功能从规范开始，然后再实现：
1. 提出 - GitHub 问题
2. 指定 - [`docs/specs/SPEC_TEMPLATE.md`](docs/specs/SPEC_TEMPLATE.md) 或 `specs/<NNN-feature>/`
3. 审查和批准规范
4. 在功能分支上实现 `NNN-feature-slug`
5. 通过 PR 合并
贡献者：阅读 [`AGENTS.md`](AGENTS.md) 并使用 [`.github/pull_request_template.md`](.github/pull_request_template.md)。PR 标题遵循 [Conventional Commits](https://www.conventionalcommits.org/) （在 CI 中强制执行）。
## 路線图
### 第一阶段 - 基础（基本完成）
- [x] 清洁架构骨架和领域模型
- [x] 八个领域接口和 MCP 工具
- [x] 词汇检索策略
- [x] 第二大脑集成（Markdown 知识库、映射、来源）
### 第二阶段 - 检索演进
- [x] BM25 检索 - [`specs/005-bm25-retrieval/`](specs/005-bm25-retrieval/)； [`ADR-0004`](docs/adr/ADR-0004-bm25-index-cache-invalidation.md)
- [x] 基于嵌入的检索 - [`specs/006-embedding-retrieval/`](specs/006-embedding-retrieval/)（快速入门、合约）； [`ADR-0005`](docs/adr/ADR-0005-pluggable-embedding-retrieval.md)； Docker Compose 示例 [`deploy/docker-compose.embedding.example.yml`](deploy/docker-compose.embedding.example.yml)
- [ ] 混合检索和重新排序
### 第三阶段 - 高级检索
- [ ] 知识图谱遍历（`findRelatedKnowledge` 目前对整个知识库使用词汇检索，而不是图谱遍历）
- [ ] 时间检索、学习查询规划、GraphRAG
MCP 工具名称和签名在这些阶段中应保持稳定；行为和排名在相同的接口下得到改善。
## 文档
| 文档 | 内容 |
| -------- | -------- |
| [`AGENTS.md`](AGENTS.md) | 项目宪法、变量、功能 |
| [`docs/second-brain-domain.md`](docs/second-brain-domain.md) | 知识区、类型、来源证明 |
| [`docs/adr/`](docs/adr/) | 架构决策记录 |
| [`specs/`](specs/) | 功能规范和合约 |
| [`docs/specs/SPEC_TEMPLATE.md`](docs/specs/SPEC_TEMPLATE.md) | 规范模板，用于新工作 |
## 许可证
暂无 `LICENSE` 文件。在添加 `LICENSE` 文件之前，标准版权法适用；复制或分发代码超出 GitHub 显示条款可能需要获得版权持有人的许可。如果您打算商业采用该项目或重新分发，请打开一个问题以澄清许可意图。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器