agora-kb

# Agora > 一个可自主托管、完全开源的多租户**共享内存中心，用于 AI 代理**。 > 许多代理和人员编写的纯 markdown 知识，它可以**自我组织**， > 并且任何 MCP 代理都可以读取和贡献。 **状态：** **第一至三阶段已完成** — 一个本地 markdown 知识库，带有捕获 (`kb_remember`)，确定性导航查询 (`kb_query`)，和一个定时策划者 (`kb_curate`)，通过 MCP 标准输入输出接口和 `agora` 命令行界面暴露。策划者的核心是**可插拔/可替换的，通过 `adapters.yaml`** （一个本地 Ollama 模型或任何无头命令行代理）与每个操作的分 `plan`/`author` 路由（ADR-0015/0016），以及一个可选的**收获者**，它将其他代理的磁盘内存拉入门控候选（`agora harvest`，ADR-0007）。第三阶段添加了**网页界面** (`agora web`)：URL/PDF/office 上传提取器，一个基于 API 的 FastAPI 服务器，带有服务器渲染的 HTMX 用户界面，用于浏览/搜索/上传，一个交互式**知识图谱** (`/graph` + 一个每个笔记的本地图谱；使用 MIT force-graph， 无 Node — ADR-0021)，一个只读的**仪表盘** （知识库健康 · 策划者 · 收获者），以及一个 Prometheus `/metrics` 导出器（ADR-0019/0020/0021）。第四至五阶段（多租户，身份验证，治理）仍在进行中；参见 [`docs/ROADMAP.md`](docs/ROADMAP.md)。软件包/分发名称：`agora-kb`。 --- ## 什么是 Agora Agora 是一个知识库，位于您（和您的团队）与原始来源之间，以**相互链接的 markdown 文件存储在 git 中** — 无需矢量数据库。检索是**导航**（读取索引 → 跟随 `[[链接]]` → grep），就像编码代理已经读取代码库一样。 与静态 wiki 不同，Agora 有一个**后台策划者**：一个代理，定时吸收捕获的内容，总结它，归档到正确的主题下，更新索引和反向链接，并合并重复项 — 人类永远无法持续的簿记工作。这是在**睡眠时间 / “梦境”模式**（cf. Letta 睡眠时间代理，Anthropic Dreaming）应用于 **markdown + 本地 LLM** 存储。 Agora 是**工具无关的**：Claude Code，Codex，Gemini CLI，Qwen Code，OpenCode，Hermes，以及任何 MCP 客户端都可以**写入知识**和**查询**。策划者的“大脑”本身是可插拔的 — 任何无头命令行代理 + 任何模型（默认：本地开放权重模型，零 API 成本）。 ## 为什么 - **积累知识，而不是重新发现。** RAG 每次查询都会重新推导知识；Agora 编译一次并保持最新。交叉引用和矛盾已经被解决。 - **跨代理共享。** 一个知识库，任何代理都可以贡献和读取 → 代理（和团队）随着使用变得更智能。 - **属于你。** 纯 markdown 存储在磁盘上，通过 git 版本控制，自我托管。没有锁定，没有上传。 - **开源，从上到下。** 每个组件都有一个宽松的开源许可（参见 [`docs/DESIGN.md`](docs/DESIGN.md) 中的 BOM）；专有代理是**可选插件**。 ## 核心思想（一屏） - **一个核心 API，多张面孔。** `write→inbox · read→wiki · meta` 是唯一的入口点；**MCP 服务器**（代理），**网页应用**（人员，上传），和**仪表盘**（状态）都是在其上的面孔。没有面孔可以绕过管道 → 并发性和访问控制是统一的。 - **CQRS + 单写入者策划者。** 许多写入者将内容追加到一个不可变的，每个写入者的收件箱（无冲突）；恰好一个策划者进程编辑共享的 wiki/索引/日志（无竞争）。git 是审计日志和乐观并发的后备。 - **三个可插拔适配器** （脊柱）： - **输入适配器** — 上传提取器（URL，PDF，docx → markdown） - **读取适配器** — 从其他代理的内存系统中拉取的**收获者** → 候选 - **写入适配器** — 策划者的**大脑** （一个无头命令行代理，可通过配置交换） - **存储库 = 租户边界。** 团队存储库和个人存储库是平等的公民，具有严格隔离的基于角色和（可选）基于域的访问控制。 ## 快速入门（本地，无云，无身份验证） 在您的机器上运行：一个本地 markdown 存储库，一个本地模型（默认为 Qwen via Ollama），无需云，无需身份验证。需要 **Python 3.12+** 和 [`uv`](https://docs.astral.sh/uv/)。 ```bash # 1. 安装项目 uv sync # 2. 创建一个知识存储库（注意：是 `agora repo init`，而不是 `agora init`） uv run agora repo init ~/my-kb --name my-kb --domain general # 3. 健康检查 — git，依赖项，策划者 OS 沙箱自测试（ADR-0013） uv run agora doctor --repo ~/my-kb # 4. （可选）导入现有的 Obsidian/markdown 保险库 — 非破坏性的：源代码仅为只读；一个新的规范化的 Agora 存储库被写入目标。 uv run agora import ~/existing-vault ~/my-kb --domain general # 5. 在 stdio 上运行 MCP 服务器面孔（MCP 客户端连接到的） uv run agora serve --repo ~/my-kb ``` 将 stdio 服务器注册到任何 MCP 客户端，四个工具 — `kb_remember`，`kb_query`，`kb_status`，`kb_curate` — 对代理可见： ```bash # Claude Code（其他 MCP 客户端：通过 stdio 将它们指向 `agora serve --repo ~/my-kb`） claude mcp add agora-kb -- uv run --directory /path/to/agora-kb agora serve --repo ~/my-kb ``` 循环：一个代理调用 **`kb_remember`** 来捕获一个事实（它进入只追加的收件箱），**`kb_curate`** 将收件箱合并到 wiki 中使用本地模型，以及 **`kb_query`** 来获取引用的证据。您可以使用 CLI 在没有代理的情况下驱动相同的循环 — `agora status`（收件箱深度 + 策划者状态），`agora curate`（一次合并运行），以及 `agora watch`（调度循环：cron + 阈值 + 空闲触发器）。 **第 2 阶段（可插拔的大脑 + 收获者）。** 要交换策划者的核心，请在 `adapters.yaml` 中添加一个 `default_backend`（和可选的 `routing: {plan, author}`），并运行 `agora curate --backend NAME`（ADR-0015）；任何无头命令行代理都可以通过 `agora-cli-brain` 成为大脑（ADR-0016）。要将另一个代理的磁盘内存（例如 `~/.claude/**/MEMORY.md`）拉入收件箱作为门控低置信度候选，请在 `adapters.yaml` 中声明一个 `connectors:` 块，在 `_kb/repo.yaml` 中启用 `harvest.enabled`，然后使用 `agora harvest --dry-run` 预览并运行 `agora harvest`（ADR-0007/0018）。`agora doctor` 打印路由表和配置的连接器。 **第 3 阶段（网页面孔）。** 可选的网页界面位于 `web`/`ingest`/`metrics` 扩展名后面，因此核心保持轻依赖。安装它们并在您的存储库上启动 FastAPI + HTMX 面孔： ```bash # 安装 web/upload/metrics 扩展（所有宽松的 OSS；延迟导入） uv sync --extra web --extra ingest --extra metrics # 运行网页面孔 — localhost，单用户，无身份验证（ADR-0019） uv run agora web --repo ~/my-kb # → http://127.0.0.1:8000 ``` 您将获得一个浏览/搜索 UI（markdown 渲染为 XSS 安全 via `markdown-it-py`），一个**上传**页面，运行 URL/PDF/office 提取器，并将结果写入收件箱（策划者仍然是 `raw/` 的唯一写入者；ADR-0020），一个一级的 JSON API 在 `/api/*` 下，一个交互式 **`/graph`** 知识图谱（以及每个笔记的本地/反向链接图谱；画布拖动/缩放/点击 → 笔记，使用 MIT force-graph，无 Node — ADR-0021），一个只读的 **`/dashboard`** （知识库健康 · 策划者 · 收获者 · 黄金包状态，HTMX 轮询），以及一个 Prometheus **`/metrics`** 端点用于外部抓取。它默认绑定到 `127.0.0.1`，不附带身份验证 — 请保持本地。 **黄金上下文包（ADR-0027）。** 在可搜索的 wiki 之上，Agora 汇集了一个**黄金**层级：一个小，token-budgeted，字节稳定的您最有价值的主题笔记切片，旨在在代理会话开始时注入（每个 CLI 代理都想要的 CLAUDE.md 样式的固定上下文）。它是一个 *纯粹的，确定性的（精选的提交，包规格）* 函数； reader-class 代码组装逐字总结行；没有 LLM 运行，没有东西写入 wiki。策划者在每次合并后重建它（它从未比 wiki 更过时），或者显式构建： ```bash uv run agora gold build --repo ~/my-kb # → _kb/gold/default.md (+ .meta.json 边车) uv run agora gold status --repo ~/my-kb # 存在 + 实时 vs 精选提示 uv run agora gold build --check --repo ~/my-kb # CI：验证字节相同的重建（如果漂移，则退出 1） ``` **仅拉取并使用** — 在您的代理配置中添加一行 include（include 本身是您的同意；Agora 从不写入代理配置目录）： ``` @~/my-kb/_kb/gold/default.md ``` 每个包都包裹在一个 `<!-- agora:pack … -->` 标记跨度中，收获者将整个跨度删除，因此注入的包循环到 **零** 重新收获的事实，并且收获源笔记从包中排除 — 黄金永远不能成为提示注入放大器（ADR-0027 §8）。MCP `kb_context` 工具和网页 `/api/gold` 消费渠道是延迟的后续工作（阶段 C）。 ## 文档 | 文档 | 内容 | |---|---| | [`docs/DESIGN.md`](docs/DESIGN.md) | 完整设计 — 核心，租户，收获者，网页/仪表盘，OSS BOM | | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 组件，数据流，部署拓扑 | | [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md) | 具体模式：收件箱项目，存储库元数据，状态，溯源 | | [`docs/ROADMAP.md`](docs/ROADMAP.md) | 分阶段路径：个人 MVP → 收获者 → 团队服务器 | | [`docs/adr/`](docs/adr/) | 架构决策记录（每个选择背后的原因） | ## 许可证 Apache-2.0（参见 [`LICENSE`](LICENSE)）— 宽松的，以最大化采用。