pulse8-ai-cortex-knowledge-vault

PULSE8.ai Cortex

面向 AI Agent 的开源知识层
知识不断积累。

PULSE8.ai Cortex 是面向 AI Agent 的开源知识层：基于 Git 的记忆、类型化知识图谱，以及由 MCP 驱动的检索，构建于纯 Markdown 之上 — 让 Agent 能够构建、演进并复用持久知识，而不必在每次查询时重新推导。

在底层，它是面向 AI Agent 和人类的统一知识库，由类型化知识图谱、全文与混合搜索，以及由 MarkItDown 驱动的文件编译器提供支持。放入文件（PDF、DOCX、PPTX、XLSX、HTML、图像等），即可让 Agent 读取、写入、搜索、链接和编译知识 — 无需数据库。

灵感来自 Andrej Karpathy 的 LLM Wiki 模式 — 由 LLM 维护的持久、不断积累的知识库，无需在每次查询时重新推导。搜索由 Tobi Lütke 的 QMD 提供支持。

---

为什么选择 PULSE8.ai Cortex？

大多数 AI Agent 可以访问工具，但无法积累知识。

传统 RAG 系统检索文档。PULSE8.ai Cortex 则构建一个持久、不断演进的知识层，随着时间推移不断增长，并在 Agent 和人类与之交互时变得更有价值。

借助 PULSE8.ai Cortex，Agent 可以：

• 从交互中学习 — 每次读取、写入、摄取和编译事件都会记录并关联到图谱中
• 构建和遍历知识图谱 — 自动维护维基链接、标签和类型化边
• 存储结构化见解 — 使用类型化节点（note、agent_def、session、daily、feedback）的 Markdown 笔记
• 跨项目检索上下文 — vault_context 可根据任意种子查询构建排序后的子图
• 通过 MCP 共享知识 — 一个知识库，供所有兼容 MCP 的客户端使用
• 维护长期记忆 — 文件在会话、部署和模型升级后依然保留
• 通过 Git 管理知识版本 — 知识库是一个纯 Markdown 目录，开箱即支持差异对比

方面	传统 RAG	PULSE8.ai Cortex
重点	文档	知识
记忆	基于会话	持久
结构	文本块	Markdown + 类型化图谱
演进	静态索引	持续更新、文件监视
版本控制	无	原生支持 Git
Agent 协作	有限	一流支持（MCP）

何时使用 PULSE8.ai Cortex

理想使用场景

• ✅ 为 AI Agent 提供持久记忆
• ✅ 多个 Agent 共享知识
• ✅ 通过 Git 进行版本管理的组织知识
• ✅ 兼容 MCP 的知识检索
• ✅ 无需专用图数据库的知识图谱
• ✅ 长期积累机构知识
• ✅ 人类与 AI 协作管理知识

不适合的场景

• ❌ 简单的全文档搜索（请使用搜索引擎）
• ❌ 纯向量检索，不涉及图谱（请使用向量数据库）
• ❌ 短暂、无状态的对话
• ❌ 不需要持续演进知识的工作流

PULSE8.ai Cortex 与其他方案的比较

能力	PULSE8.ai Cortex	传统 RAG	GraphRAG
持久知识	✅	❌	⚠️
原生支持 Markdown 存储	✅	❌	❌
开箱即兼容 MCP	✅	❌	❌
知识图谱	✅	❌	✅
Git 版本管理	✅	❌	❌
Agent 记忆层	✅	❌	⚠️
人类与 AI 协作	✅	❌	⚠️
知识持续演进	✅	❌	⚠️
无需数据库	✅	❌	❌

兼容工具

PULSE8.ai Cortex 使用 MCP 协议，因此可接入任何支持 MCP 的 AI 客户端。同一个知识库可通过可流式传输的 HTTP 或 stdio 访问，并由 /api/v1/ 下的 REST API 进行 1:1 镜像。

类别	兼容对象
AI Agent	Claude Desktop、Claude Code、OpenAI Agents、Gemini、自定义 Agent 框架
开发工具	Cursor、VS Code、JetBrains IDE
Agent 框架	LangGraph、LangChain、CrewAI、AutoGen
MCP 生态	MCP 客户端、MCP 服务、MCP 工具注册表
人类使用的工具	Obsidian、任何 Markdown 编辑器、任何 Git 客户端

由于知识库只是文件，人类和 Agent 可以协作使用同一份知识，无专有格式，也不会被锁定。

开始使用

说明

PULSE8.ai Cortex 需要 Docker。 OpenRouter API key 为可选项，仅用于 Wiki 文章之间由大模型驱动的交叉引用。文件转换无需任何 API key 即可开箱使用。

1. 克隆仓库：

  git clone https://github.com/synpulse8-opensource/pulse8-ai-cortex-knowledge-vault.git
  cd cortex-knowledge-vault

2. 启动 PULSE8.ai Cortex：

  ./scripts/start.sh

这会构建并启动 **PULSE8.ai Cortex**（API + MCP，运行于 `:8420`）和 **QMD**（搜索，运行于 `:3100`），等待健康检查通过后即可开始使用。

3. 将 MCP 客户端（例如 Claude Desktop）连接到 http://localhost:8420/mcp/。

停止运行：./scripts/stop.sh

原生 QMD 模式（macOS / Metal GPU）

macOS 上的 Docker Desktop 无法向容器开放 Metal GPU，因此容器中的 QMD 只能在 CPU 上生成嵌入，在非简单知识库上速度会慢一个数量级以上。请改为原生运行 QMD；qmd 二进制文件会自动使用 Metal：

# One-time: install the qmd binary
brew install tobi/tap/qmd   # or: npm install -g @tobilu/qmd

# Start native QMD (background daemon) + Cortex in Docker
./scripts/start.sh --native-qmd

QMD 守护进程的 pid 和日志保存在 .qmd-native.pid / .qmd-native.log 中。停止两者：./scripts/stop.sh --native-qmd（如果原生 QMD 正在运行，直接执行 ./scripts/stop.sh 也会将其停止）。

仅 Cortex 模式（外部 QMD）

如果你自行管理 QMD（已在其他位置运行），则只启动 Cortex 容器：

./scripts/start.sh --cortex-only   # set QMD_URL in .env if not http://host.docker.internal:3100

停止运行：./scripts/stop.sh --cortex-only

GPU 加速的 QMD（EC2 / 配备 NVIDIA GPU 的 Linux）

用于生产部署的 NVIDIA GPU 加速：

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build -d

请参阅 docs/ec2-gpu-setup.md，了解实例选择、NVIDIA 工具包安装和成本估算的完整指南。

功能

知识图谱	类型化图引擎（NetworkX）——支持维基链接、标签和自定义边，并在每次文件变更时自动维护
全文搜索	默认使用混合搜索（BM25 + 向量 + 重排序）的 QMD 搜索；可选择关键词和语义模式。搜索结果会按可配置的 TTL 缓存。
文件编译器	通过 MarkItDown 将原始文件（PDF、DOCX、PPTX、XLSX、HTML、图像等）转换为 Markdown。仅在交叉引用时使用大模型。
MCP 服务	支持 Streamable HTTP + stdio 传输——可与 Claude Desktop、Cursor 和任何 MCP 客户端配合使用
反馈与通知	vault_feedback 会将质量反馈记录为笔记；可选的 Microsoft Teams webhook 会为每次提交发布一张自适应卡片
每日活动日志	每次写入 / 摄取 / 编译都会同步记录到 daily/<date>.md，形成可搜索且包含维基链接的时间线
批量摄取	一次从本地目录摄取数十或数百个文件，支持 SHA-256 去重和有界并发
REST API	FastAPI 端点在 /api/v1/ 下映射所有 MCP 工具，包括 multipart 文件上传和批量摄取
知识库监视器	实时文件系统监控——图谱会自动保持同步
溯源与审计	每条边都标记为 extracted / inferred / manual；vault_trace 可追溯“知识库为何如此表述 X”，直达源文档
图查询	vault_path（X 和 Y 之间的连接）、vault_impact（此笔记的下游内容）、vault_explain（带溯源信息的实体摘要）
整理报告	阅读计数器和结果反馈（useful / dead-end / corrected）可在 GET /api/v1/curation/report 中显示过时、相互矛盾及从未阅读的笔记
零数据库	所有内容都以 Markdown + JSON 的形式保存在你的文件系统中

基准测试

在 LongMemEval-S 上的总体准确率为 45.0%（500 个问题、完整的文本集合、混合搜索），证据召回率@8 为 65.6%，且评判器错误为零——通过公开 REST API 端到端测得：摄取 → 编译 → 图谱 → 搜索 → 回答。

类别	准确率	召回率@8
单会话-助手	96.4%	98.2%
单会话-用户	71.4%	78.6%
知识更新	60.3%	75.6%
时间推理	25.6%	51.1%
多会话	24.8%	54.1%
单会话-偏好	23.3%	63.3%

所有数据均可通过一条命令，使用固定配置（数据集 SHA-256、模型、随机种子）复现：

uv run python -m evals.run_longmemeval --config evals/configs/longmemeval-s-hybrid.yaml

测试框架（evals/）会发布每个问题的 JSONL 跟踪记录，将评判模型与回答模型分开，使用 LongMemEval 官方的分类评分提示词，并包含对评判器的盲法人类验证。完整的方法说明、注意事项和原始结果见：docs/benchmarks/。

无需 LLM 即可运行

Cortex 优先采用确定性方案：摄取（MarkItDown 转换）、知识图谱（wikilinks、标签、derived_from 边）和 QMD 搜索均可在零次 LLM 调用的情况下运行。LLM 是可选的增强步骤——用于交叉引用、添加标签、生成图像说明——并非依赖项。

通过 LLM_BACKEND（环境变量）/ CORTEX_LLM_BACKEND（Python）选择后端：

后端	支持内容
openai-compatible（默认）	OpenRouter、Azure OpenAI、Ollama、vLLM、LM Studio——任何使用 OpenAI 协议的服务。将 LLM_BASE_URL 指向你的端点。
bedrock	通过标准 AWS 凭证链使用 AWS Bedrock（无需 API 密钥）。需要 boto3。
none	显式启用零 LLM 模式。保证不会构建 LLM 客户端，也不会调用模型——适用于气隙部署。

使用本地 Ollama 的气隙部署示例：

LLM_BACKEND=openai-compatible \
LLM_BASE_URL=http://localhost:11434/v1 \
LLM_API_KEY=ollama \
COMPILER_MODEL=llama3.1 \
./scripts/start.sh

或者完全采用确定性模式：LLM_BACKEND=none ./scripts/start.sh（无需 API 密钥）。

MCP 资源（节省令牌的大型负载）

PULSE8.ai Cortex 实现了 Microsoft Copilot Studio CAT 团队推荐的将资源用作工具输入的模式：令牌消耗较大的工具输出（大型搜索结果集、完整上下文窗口）可以保留在服务端，并作为轻量句柄在工具之间传递，从而保持较小的 LLM 上下文窗口。

工作原理。 向 vault_search 或 vault_context 传入 as_resource: true（或在 GET /api/v1/search 中使用 ?as_resource=true）。系统不会内联完整负载，而是返回一个句柄：

{
  "resource_id": "7f8a3c...",
  "resource_uri": "cortex://resource/7f8a3c...",
  "summary": { "query": "...", "count": 8, "paths": ["..."] }
}

通过以下三种传输方式中的任意一种读取资源：

• MCP 资源协议——使用 cortex://resource/{id} URI 调用 resources/read（Claude Desktop、Cursor、Copilot Studio MCP）。
• 备用工具——对于只向规划层公开工具的客户端，使用 vault_resource_read（某些 Copilot Studio 配置）。
• REST——GET /api/v1/resources/{resource_id}（接受裸 ID 或完整 URI）。

存储采用内存方式，支持 asyncio，可按 TTL 淘汰，并受 LRU 容量限制：

环境变量	默认值	用途
CORTEX_RESOURCE_TTL_SECONDS	3600	已存储资源在读取时延迟淘汰前的最长保留时间
CORTEX_RESOURCE_MAX_ITEMS	1000	LRU 容量上限；超出时丢弃最早的条目

MCP 和 REST 共用同一个 ResourceStore——可以通过 MCP 创建句柄，再通过 REST 读取（反之亦然）。

docs/copilot-studio.md 记录了 Microsoft Copilot Studio 的设置方法——包括 Agent 指令、工具选择和 Custom Connector 备用方案。无需更改 Cortex 代码。

MCP 工具

工具	描述
vault_read	按路径读取笔记
vault_write	创建或更新笔记
vault_search	搜索知识库（关键词／语义／混合）。支持 as_resource=true
vault_link	创建、查询或删除图边
vault_context	构建上下文窗口：搜索 → 图遍历 → 排序后的子图。支持 as_resource=true
vault_ingest	导入原始内容或二进制文件（二进制文件支持 content_base64）
vault_compile	通过 MarkItDown 将未经处理的原始来源编译为 Wiki Markdown
vault_feedback	提交关于知识库质量的反馈（status: OPEN；可选 related_paths 和 outcome：有用／无结果／已更正）
vault_list_feedbacks	列出反馈笔记的元数据（路径、标签、状态；不含正文）
vault_resource_read	按 ID 读取服务端存储的 MCP 资源（为不支持 resources/read 的客户端提供备用方案）
vault_trace	追溯笔记的沿袭关系：来源信息、原始来源以及标记为 extracted／inferred／manual 的边
vault_path	查找两篇笔记之间的最短路径——“什么将 X 与 Y 联系起来”，并标注每一跳的类型和来源
vault_impact	遍历笔记下游的所有内容（变更影响分析）
vault_explain	解释笔记：摘要、来源信息、来源、入链／出链、矛盾

架构

┌──────────────────────────────────────────────┐
│  MCP Client (Claude Desktop, Cursor, etc.)   │
└──────────┬───────────────────────────────────┘
           │  MCP (HTTP or stdio)
┌──────────▼───────────────────────────────────┐
│  PULSE8.ai Cortex  :8420                     │
│  ┌──────────────────────────────────────┐     │
│  │ Auth (API Key or Microsoft Entra ID) │     │
│  └──────────────┬───────────────────────┘     │
│  ┌─────────┐ ┌──┴───────┐ ┌──────────────┐   │
│  │ MCP     │ │ REST API │ │ Vault Watcher│   │
│  │ /mcp/   │ │ /api/v1/ │ │ (watchfiles) │   │
│  └────┬────┘ └────┬─────┘ └──────┬───────┘   │
│       └───────────┼──────────────┘           │
│            ┌──────▼──────┐                   │
│            │ Graph Engine│                   │
│            │ + Compiler  │                   │
│            └─────────────┘                   │
└──────────┬───────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────┐
│  QMD  :3100                                  │
│  BM25 + vector search, auto-indexes on start │
└──────────┬───────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────┐
│  Vault (bind-mounted volume)                 │
│  wiki/ raw/ agents/ sessions/ daily/ feedback/ │
│  .cortex/ (graph.json, index.md, log.md)     │
└──────────────────────────────────────────────┘

知识库目录结构

知识库是一个按用途组织的纯 Markdown 文件目录。Cortex 会将每个文件归类为带类型的节点（NodeType），供图引擎使用，并通过 REST 和 MCP 响应公开。

文件夹	NodeType	用途
wiki/	note	已编译且相互链接的知识文章
raw/	raw_source	未经处理的来源（PDF、DOCX、TXT 等），由编译器读取
agents/	agent_def	Agent 定义
sessions/	session	每个会话的笔记／对话记录
daily/	daily	每日笔记（Obsidian Daily Notes 约定）
feedback/	feedback	关于知识库质量的反馈（status、related_paths）
.cortex/	(跳过)	Cortex 内部文件——graph.json、index.md、log.md、清单

分类方式

优先级顺序（从上到下，匹配首项即生效）：

1. *Frontmatter type:* ——显式覆盖，始终优先（例如，agents/foo.md 中的 type: note 会被解析为 NodeType.NOTE）
2. 文件夹前缀 ——raw/ agents/ sessions/ daily/ feedback/ 下的文件会继承文件夹类型，无需文件名后缀（例如，daily/2026-06-10.md → daily）
3. 文件名后缀（向后兼容）——.agent.md、.session.md、.memory.md 在任何位置仍会生效（例如，wiki/legacy.agent.md → agent_def）
4. 默认值 ——NodeType.NOTE

这意味着，你可以直接将 YYYY-MM-DD.md 放入 daily/，或将不带后缀的 planner.md 放入 agents/，图和 API 就会正确分类，无需重命名。

每日活动日志

每个 vault_write、vault_ingest 和成功的 compile 事件（MCP 和 REST 路径）都会自动镜像到当天的 UTC 日记 daily/YYYY-MM-DD.md 中。该文件会在当天首次发生事件时创建，之后每个事件都会追加一个 ## [HH:MM] event | summary 块和一个 [[wiki-stem]] 维基链接（这样监视器就会为受影响的笔记绘制 LINKS_TO 边）。格式遵循 Karpathy 的 log.md 可 grep 前缀模式——grep "^## \[" daily/2026-06-10.md 可以获得当天清晰的时间线。

写入 daily/、feedback/ 或 .cortex/ 的内容不会被镜像，以避免产生自指噪声。隐藏的 .cortex/log.md 审计日志不受影响，仍会记录每项操作。

批量摄取

一次摄取多个文件（几十或数百份 PDF、论文、文档）时，请使用一键式 shell 脚本，而不要通过 MCP 逐个处理。该脚本直接从本地目录读取文件（递归读取，包括子文件夹）——无需网络传输开销，也无需运行服务端——通过 SHA-256 哈希去重，以有限并发量进行编译，并在最后重建一次索引。子路径会保留在知识库的原始文件夹下（例如，source/abcde/doc.html → raw/abcde/doc.html）。

一键脚本（推荐）

# Ingest all files from a directory
./scripts/bulk_ingest.sh ./my-papers/

# Dry-run to preview what would be ingested
./scripts/bulk_ingest.sh ./my-papers/ --dry-run

# Force re-ingest (bypass dedup manifest)
./scripts/bulk_ingest.sh ./my-papers/ --force

# Control LLM concurrency (default: 4)
./scripts/bulk_ingest.sh ./my-papers/ --concurrency 8

脚本会自动加载 .env 中的 LLM 密钥和知识库路径，打印摘要，然后运行完整流程（复制、编译、重新索引）。无需运行 Cortex 服务端。

Python CLI（直接使用）

CORTEX_VAULT_PATH=./example_vault uv run cortex-bulk-ingest --source ./my-papers/

在 Docker 中

# Set INGEST_DIR in .env or export it, then restart
export INGEST_DIR=/path/to/your/papers
docker compose up -d

# Run bulk ingest inside the container
docker exec pulse8-ai-cortex uv run cortex-bulk-ingest --source /ingest

通过 REST API

以编程方式使用，且无需 MCP（需要运行中的 Cortex 服务端）：

curl -X POST http://localhost:8420/api/v1/bulk-ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-secret-api-key" \
  -d '{"source_dir": "/ingest", "concurrency": 4}'

去重

去重清单存储在 .cortex/ingest-manifest.json 中。文件根据内容哈希匹配，而非文件名——重命名文件不会导致重新摄取，具有不同名称但内容相同的文件也会被跳过。

配置

复制示例并填写你的值：

cp .env.example .env

变量	必需	默认值	描述
LLM_BACKEND	否	openai-compatible	大模型后端：openai-compatible、bedrock（AWS 凭证链）或 none（不调用大模型）
LLM_API_KEY	否	—	OpenRouter（或兼容服务）的 API 密钥（仅用于交叉引用）
COMPILER_MODEL	否	anthropic/claude-sonnet-4	用于检测交叉引用的模型
LLM_BASE_URL	否	https://openrouter.ai/api/v1	大模型 API 基础 URL
VAULT_DIR	否	./example_vault	知识库目录的路径
INGEST_DIR	否	./ingest	批量导入源目录的路径（在 Docker 中挂载为 /ingest）
QMD_REFRESH_INTERVAL_SECONDS	否	900	定期重新索引的间隔（秒；设为 0 可禁用）
QMD_SEARCH_MODE	否	hybrid	未指定时使用的默认搜索模式：hybrid（BM25 + 向量 + 重排序）、semantic 或 keyword
QMD_CACHE_TTL_SECONDS	否	30	搜索结果缓存的 TTL；对于以读取为主的知识库，可调高此值以跳过重复的 QMD 调用
QMD_SEARCH_TIMEOUT_SECONDS	否	120	每个请求的搜索超时时间（仅使用 CPU 的主机上运行混合搜索时可调高此值）
QMD_EMBED_TIMEOUT_MS	否	600000	嵌入超时时间（毫秒；仅使用 CPU 的部署环境中可调高此值）
QMD_URL	否	—	仅使用 cortex 模式时的外部 QMD URL（例如 http://host.docker.internal:3100）
AUTH_METHOD	否	none	身份验证方式：none、apikey 或 oidc（参见身份验证）
API_KEY	否	—	用于 x-api-key 标头的静态 API 密钥（在 AUTH_METHOD=apikey 时使用）
OIDC_TENANT_ID	否	—	Microsoft Entra ID 租户 ID（在 AUTH_METHOD=oidc 时使用）
OIDC_CLIENT_ID	否	—	Microsoft Entra ID 应用（客户端）ID
OIDC_CLIENT_SECRET	否	—	Microsoft Entra ID 客户端密钥
OIDC_BASE_URL	否	http://localhost:8420	Cortex 服务的公共基础 URL（用于 OAuth 回调）
TEAMS_WEBHOOK_URL	否	—	传入 Webhook / Power Automate URL；每收到一条新的反馈笔记时都会发送自适应卡片
TEAMS_APP_BASE_URL	否	—	可选的 Cortex 公共基础 URL，用于在 Teams 卡片中添加“在 Cortex 中查看”链接
OPENROUTER_API_KEY 和 CORTEX_LLM_API_KEY 可作为 LLM_API_KEY 的别名。上面的变量在 .env 中设置（Docker 通过 Compose 读取），并映射到应用使用的 CORTEX_* 设置。

身份验证

Cortex 支持两种身份验证方式，可保护 REST API（/api/v1/）和 MCP 端点（/mcp/）。在 .env 中设置 AUTH_METHOD 进行选择：

AUTH_METHOD	描述
none	默认。所有端点均开放——无需身份验证。
apikey	静态 API 密钥。客户端在请求中传递 x-api-key 标头。
oidc	Microsoft Entra ID（Azure AD），支持 OAuth 2.0 + MFA。

API 密钥（AUTH_METHOD=apikey）

最简单的选项。在 .env 中设置方法和密钥：

AUTH_METHOD=apikey
API_KEY=your-secret-api-key

客户端通过 x-api-key 标头传递密钥：

# REST API
curl http://localhost:8420/api/v1/health \
  -H "x-api-key: your-secret-api-key"

# MCP (via curl)
curl -X POST http://localhost:8420/mcp/ \
  -H "x-api-key: your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

不会提供 OAuth 发现端点——也不会弹出登录窗口。未提供有效密钥的请求会收到 401 响应。

Microsoft Entra ID（AUTH_METHOD=oidc）

适用于需要交互式登录并支持 MFA 的企业环境：

AUTH_METHOD=oidc
OIDC_TENANT_ID=your-tenant-id
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_BASE_URL=http://localhost:8420

启用以下功能：

• REST API：通过 GET /api/v1/login 使用 OAuth 2.0 授权码流程。登录后，将访问令牌作为 Authorization: Bearer <token> 传递。设置了 API_KEY 时，也接受有效的 x-api-key 标头作为备用方式。
• MCP 端点：FastMCP 内置的 OIDCProxy 可处理基于浏览器的交互式登录。

Azure AD 应用注册

要使用 OIDC，请在 Azure Portal 中注册应用：

1. 前往 Azure Active Directory → App registrations → New registration
2. 将重定向 URI 设置为 http://localhost:8420/api/v1/auth/callback（Web 平台）
3. 在 Certificates & secrets 下创建客户端密钥
4. 在 API permissions 下添加 openid、profile 和 email（Microsoft Graph → Delegated）
5. 将 Tenant ID、Client ID 和 Client Secret 复制到 .env 中

MCP 客户端设置

Claude Desktop

示例配置位于 [claude_desktop_config.example.json](claude_desktop_config.example.json)。

使用 API 密钥的 HTTP（推荐）——PULSE8.ai Cortex 作为常驻服务运行：

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8420/mcp/",
      "headers": {
        "x-api-key": "your-secret-api-key"
      }
    }
  }
}

无身份验证的 HTTP——未配置身份验证时使用：

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8420/mcp/"
    }
  }
}

Stdio——Claude Desktop 按需启动服务（无需身份验证）：

{
  "mcpServers": {
    "cortex": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/cortex", "python", "-m", "cortex.mcp"],
      "env": {
        "CORTEX_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8420/mcp/",
      "headers": {
        "x-api-key": "your-secret-api-key"
      }
    }
  }
}

工作原理

Watcher 和 Compiler 是相互独立的组件：

• Watcher 负责维护图谱。添加、修改或删除任何 .md 文件都会触发节点和边的自动更新。
• Compiler 使用 MarkItDown 将原始源文件转换为 Markdown，并写入 wiki/。支持的格式包括 PDF、DOCX、PPTX、XLSX、HTML、CSV、JSON、XML、图像（EXIF/OCR）和纯文本。大模型仅用于可选的文章间交叉引用检测。

它们通过间接方式协作：Compiler 写入 wiki/，Watcher 获取这些文件并更新图谱。

支持的文件格式

格式	扩展名
PDF	.pdf
Microsoft Word	.docx
Microsoft PowerPoint	.pptx
Microsoft Excel	.xlsx、.xls
HTML	.html、.htm
基于文本的格式	.csv、.json、.xml、.txt、.md
图片	.jpg、.png 等（EXIF 元数据）

搜索采用两阶段管道：

1. QMD 对文件内容执行关键词／语义搜索
2. PULSE8.ai Cortex 通过图边（wikilinks、标签、匹配笔记之间的关系）丰富结果

QMD 回答*“哪些内容相关？”——图谱则回答“这些结果之间有什么关联？”*

实际应用场景

软件工程知识库

• 架构决策记录（ADR）
• 编码标准和规范
• 工程手册和运行手册
• 平台和服务文档
• 领域驱动设计模型

银行与金融服务

• 产品文档
• 监管与合规知识
• 业务领域模型
• 财富管理专业知识
• 机构流程经验

企业知识管理

• 内部 Wiki
• 项目文档和复盘
• 经验教训和回顾
• 组织记忆
• 最佳实践和操作指南

AI Agent 记忆层

• Agent 间共享记忆
• 长期推理上下文
• 跨会话积累知识
• 多个 Agent 在单个知识库中协作

路线图

近期

• 增强知识图谱可视化
• Agent 活动时间线
• 知识质量评分
• 更多 MCP 集成

中期

• 多知识库联邦
• 企业治理和访问策略
• 知识谱系跟踪
• 跨 Agent 学习信号

长期

• 自我改进的组织记忆
• 自主知识整理
• 知识驱动的 Agent 生态系统

开发

# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run shell tests (requires bats-core)
bats tests/test_start_sh.bats

# Start PULSE8.ai Cortex locally (without Docker)
CORTEX_MCP_TRANSPORT=http CORTEX_VAULT_PATH=./example_vault uv run python scripts/serve.py

实用脚本

脚本	描述
scripts/serve.py	开发服务器（根据 CORTEX_MCP_TRANSPORT 使用 HTTP 或 stdio）
scripts/compile.py	批量编译所有原始来源
scripts/reindex.py	完整重新索引并重建图谱
scripts/bulk_ingest.sh	从本地目录一键批量导入
scripts/bulk_ingest.py	用于批量导入的 Python CLI（由 bulk_ingest.sh 调用）
scripts/lint.py	检查知识库结构

数据持久化

知识库目录通过绑定挂载从主机映射到容器中。所有数据都保存在本地磁盘上，即使容器重启也会保留。

QMD 搜索索引存储在 Docker 卷（qmd-cache）中。要强制执行完整重新索引：

docker compose down -v
./scripts/start.sh

发布

发布流程通过 GitHub Actions 自动化。发布 GitHub Release 会触发三个工作流，构建并发布所有内容：

工作流	发布到
publish-pypi.yml	PyPI
publish-docker.yml	GitHub Container Registry（ghcr.io）
publish-mcp.yml	MCP Registry（GitHub OIDC 身份验证）

发布新版本：

1. 递增版本号：在 pyproject.toml 和 server.json 中更新版本号（保持一致），更新 CHANGELOG.md，然后提交到 main。

   # optional: validate the registry manifest locally before tagging
   mcp-publisher validate
   

2. 创建 GitHub Release——通过 UI（Releases →“Draft a new release”→ 新建标签 vX.Y.Z）或 CLI：

   git tag vX.Y.Z && git push origin vX.Y.Z
   gh release create vX.Y.Z --title "vX.Y.Z" --notes-file docs/releases/vX.Y.Z.md
   

3. 完成——发布事件会触发全部三个工作流。publish-mcp.yml 会等待 PyPI 提供新版本（以便验证此 README 中的 mcp-name 所有权标记），然后通过 GitHub OIDC 在 io.github.synpulse8-opensource/* 名下发布服务（无需令牌或本地 mcp-publisher）。

4. 工作流完成后，验证注册表条目：

   curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=pulse8-ai-cortex-knowledge-vault"
   

重要

PyPI 版本不可变——即使删除后，也无法重复使用版本号。务必递增到新版本；切勿重新发布已有版本。

社区

我们相信 AI Agent 需要专用的知识层，而不是另一个文档存储库。如果你也认同这一愿景：

• 为代码库加星
• 发起讨论或提交问题
• 提交拉取请求（参见贡献指南）
• 分享你的使用场景——银行、工程、研究或其他领域

让我们携手构建面向 Agentic AI 的知识层。

贡献

欢迎贡献！提交拉取请求前，请先提交问题，讨论你的想法。

# Fork and clone the repo
git clone https://github.com/<your-username>/cortex-knowledge-vault.git
cd cortex-knowledge-vault

# Create a branch
git checkout -b feat/my-feature

# Install dev dependencies
uv sync --all-extras

# Make changes, then run tests
uv run pytest tests/ -v

# Submit a pull request

报告问题

请通过 GitHub Issues 报告错误或申请功能。

致谢

PULSE8.ai Cortex 建立在开源社区的理念和工具之上：

• LLM Wiki，作者 Andrej Karpathy——其核心模式是由 LLM 维护的持久化知识库，逐步编纂并关联知识，而不是每次查询时都从原始文档中重新发现知识。这篇 gist 是 Cortex 架构的直接灵感来源。
• QMD，作者 Tobi Lütke——为 Cortex 提供所有全文搜索和混合搜索能力的设备端搜索引擎。QMD 将 BM25、向量搜索和 LLM 重排序相结合，且全部在本地运行。
• MarkItDown，作者 Microsoft——为 Cortex 编译器提供支持的文件转 Markdown 转换器。它可将 PDF、Office 文档、HTML、图像等转换为结构化 Markdown，以便导入知识库。

许可证

本项目根据 PULSE8.ai Cortex 开源许可证（Apache License 2.0，附加条款）授权。