OpenLore

将一个 Markdown 文件夹交给 OpenLore，团队中的每个 Agent 都会读取相同的文件，无论使用的是 Claude Code、Codex、Cursor，还是 CI 任务。Agent 使用自己熟悉的工具，例如 cat、grep 和 find。你可以决定谁能查看和更改哪些内容。

_{一键部署托管服务。请参阅 将 OpenLore 部署到 Render。}

快速开始

安装并提供文件夹服务：

brew install --cask aakarim/tap/lore
openlore ./docs

SSH 使用端口 2222。Web 视图和 MCP 共用端口 8080。./docs 中的内容会显示在 /。

连接 Agent：

# Claude Code
claude mcp add --transport http openlore http://localhost:8080/mcp

# Codex
codex mcp add openlore --url http://localhost:8080/mcp

# Anything with a shell
ssh -p 2222 localhost "grep -r 'retry' /"

告诉你的 Agent 何时使用它：

ssh -p 2222 localhost agents >> AGENTS.md

也可以让 Agent 完成整个设置过程：

ssh openlore.sh teach | claude

没有安装 Homebrew？请参阅适用于 Linux 和 Windows 的快速入门。

为什么不直接把 Markdown 放在代码仓库里？

如果只有一个 Agent 使用一个代码仓库，就这么做。

当多个 Agent、代码仓库或人员需要共享相同的知识，并且你需要指定谁可以读取、写入或发布哪些内容时，OpenLore 就派上用场了。只需更新一次文件，每个 Agent 下次读取时都会看到新版本。

这里没有向量数据库、数据摄取流水线或 SDK。你的知识会以普通 Markdown 文件的形式保存。

指南

• 什么是 OpenLore
• Claude Code
• Codex
• Cursor
• OpenCode
• Meta Muse
• OpenAI dots
• Grok Bot
• Claude Duet
• LangChain
• 通过 SSH 使用任意 Agent
• 让 Agent 向收件箱发布内容
• 部署到 Render
• 根据分析数据清理知识库
• 在 OpenLore 上构建大模型 Wiki
• 与每个 Agent 共享编码风格指南
• 所有文档

功能

• 面向 Agent 的检索 — Agent 使用熟悉的 Shell 工具和组合模式，无需学习专门的检索 API。
• 一个知识界面，多种传输方式 — 通过 SSH、SFTP/SSHFS（包括直接在 VS Code 中浏览和编辑）、MCP，以及便于用户使用的 Web 视图，提供同一个虚拟文件系统。
• 实时、受治理的知识 — 将内容设为只读，允许限定范围的发布，或为每个文档集启用完全写入权限。写入具有原子性、可检测冲突，并会在提交前进行验证。
• 按身份限定视图 — 仅向每个人或 Agent 提供所需的文档集，并通过基于角色的 ro、publish 和 rw 授权、路径别名及私有主目录进行管理。
• 从设计上保障安全 — Shell 是内存中的 Go 解释器，而非真实的操作系统 Shell。普通会话中无法跳出 Shell、任意执行进程或访问环境网络。
• 可移植的知识包 — 将文档嵌入独立运行的二进制文件，使用 GitHub Action 构建跨平台包，或将其打包为桌面 MCP 扩展。
• 无需新查询语言的结构化知识 — 使用 lore meta 将前置元数据查看为 NDJSON，通过 jq 查询，并在写入路径附近验证 Google 的 Open Knowledge Format（OKF） 知识包和 Agent Skills。
• 可扩展的策略与处理机制 — 插件可添加验证、授权、读写中间件、元数据和提交后处理，同时保留相同的文件系统接口。

使用场景

• 持续学习知识库 - 在一个共享服务中存储会话和经验。添加指标以便优化。允许 Agent 彼此分享经验，同时保持用户隔离。
• 团队制品知识库 - 分享你创建的 Markdown、HTML、JSON、Excel 等文档，同时保持访问控制。比 Git 更自然，也比 Confluence/Notion 更适合 Agent。
• 面向编码 Agent 的文档 — 将内部 API 文档、运行手册、产品背景和架构说明放在熟悉且便于检索的界面后。
• 供多个 Agent 共享的实时记忆 — 为 Agent 提供独立或共享的文档集，以便它们发布发现、交接工作，并在不同会话中积累持久的上下文。
• 公共文档站点 - 向公共文档集添加任意文件并启用公开访问后，任何偶然访问你站点的 Agent 都能看到这些文件。无需编辑现有文档，即可提升 AEO/GEO。
• Skills 共享 — 将 Agent Skills 发布到共享集合中，让每个获授权的 Agent 都能发现并使用相同的受治理流程。
• Agent 插件知识库 — 从 GitHub 固定 Agent Plugins 仓库的版本，并将其提供给团队的 Agent。采用开放标准打包的 Skills 会自动保持最新。
• 受治理的知识贡献 — 允许贡献者发布内容到收件箱，同时将现有文档保留给维护者，并防止意外覆盖。
• 制品知识库 — 通过浏览器或 SSH 存储和公开报告、日志、屏幕截图及生成的文件，无需构建自定义制品查看器，也无需授予 Agent 访问其所在机器的权限。
• 按身份划分的工作区 — 为每个 Agent 挂载私有主目录，并提供共享团队知识，全部通过一个服务和一套授权模型实现。
• 可移植的客户或项目知识 — 发布嵌入相关文档的带版本可执行文件，或将相同知识作为 MCPB 桌面扩展分发。
• 经过验证的知识目录 — 强制执行前置元数据和知识包规范，快速检查元数据，并在接纳时阻止格式错误的知识。

工作原理

OpenLore 使用 Wish 处理 SSH 传输。连接完全通过虚拟文件系统进行：

1. 身份验证 — 无需密钥即可连接，或将 SSH 密钥、证书、 通行密钥或 OAuth 登录解析为身份。
2. 组合视图 — 仅挂载授予该身份的文档集和路径。
3. 探索 — 在该视图上运行由纯 Go 函数实现的 Shell 命令，或使用等效的 MCP lore_bash 工具。
4. 安全贡献 — 如果启用了写入功能，则先授权并验证整个文件的更改，再以原子方式提交。

OAuth 客户端使用委托身份，因此持久化的写入来源记录可以区分 adil 的直接操作和以 adil/[email protected] 身份执行的操作。委托身份继承的权限不会超过其主体，并且可以通过文档集和能力拒绝列表进一步限制。CIMD 客户端还可以通过供应商托管的元数据和 private_key_jwt 进行身份验证；请参阅 经过身份验证的 OAuth 客户端。

普通 Shell 无法调用 bash、exec、curl 或任意主机进程。内嵌文档始终为只读。明确受信任的身份可以被授予范围严格受限的异步处理能力，方式是启用 spawn 能力。

受治理的写入

OpenLore 默认只读。可写部署使用单一、受策略控制的写入路径，处理重定向、追加、tee、patch、sed -i、文件移动、发布和受信任的外部作业。

echo "# Research" | publish /backend/findings.md
cat change.diff | patch /backend/api.md
sed -i 's/old/new/g' /backend/runbook.md

写入以整个对象为单位进行原子交换。默认情况下，比较并交换保护机制会拒绝过期的编辑；文档集授权会限制目标，插件则可以在写入提交前验证或延迟写入。

有关面向用户的设置，请参阅写入和发布；有关实现模型，请参阅写入系统内部机制。

安装

有关 Homebrew、Linux 和 Windows 版本，以及哪些安装包含仪表板的信息，请参阅快速入门。如需自行构建 OpenLore，请参阅从源代码构建。

将文档嵌入二进制文件

将文档放入 assets/lore/ 并进行构建。生成的二进制文件将包含这些文档；运行时若未提供目录参数，则会通过 /docs 以只读方式提供文档：

make dashboard-build   # optional: include the web UI
go build -o my-docs ./cmd/openlore

使用 GitHub Action 构建

生成嵌入文档的跨平台二进制文件：

- uses: aakarim/openlore@v1
  with:
    docs-dir: ./docs
    config: ./openlore.yml

有关直接在 VS Code 中编辑、MCP stdio、MCPB 桌面打包、SSHFS 和 Go 库用法，请参阅使用 OpenLore 的方式。

创建自定义部署

使用随附的 setup 技能创建 <team>-lore，这是一个由客户拥有的小型仓库，其中包含 openlore.yml、一个固定到官方 OpenLore 版本的精简 Containerfile，以及部署制品。它会构建一个可运行的本地服务，并在部署前验证 HTTP、MCP、经过身份验证的 SSH、写入和持久化：

ssh openlore.sh setup | amp

生成的仓库会将初始 lore.json 策略和可通过 SSH 查看的文件保存在被 Git 忽略的 .local/ 中。首次部署会使用该状态初始化空的持久卷。根目录中的 openlore.yml 仍是 Git/IaC 的权威配置，并会单独部署到 /var/lib/openlore/config/openlore.yml；它不会被打包进映像。此后，服务端上的 lore.json 和文件系统编辑内容具有权威性，映像更新绝不会覆盖它们。

其他指令命令支持完整生命周期：

• onboarding 在本地添加初始身份、角色、主目录和文件夹；
• deploy 选择 Fly.io、Railway、AWS、Google Cloud、Azure、DigitalOcean 或自定义部署，并验证共享的持久化／网络契约；
• upgrade 仅准备固定基础映像版本的变更，以便现有的 CD 部署。

提供商部署需要 HTTPS/MCP、经过身份验证的 OpenLore SSH、管理 Shell 访问权限，以及一个持久的 /var/lib/openlore 卷。在提供商支持的情况下，部署会将公共端口 22 配置为转发到 OpenLore 端口 2222。否则，它会报告分配的端口，并建议使用外部 TCP 转发系统。

已发布的容器仅包含 OpenLore，不会包含引导策略或服务配置。服务启动前，部署必须将 openlore.yml 和 lore.json 放入持久化配置目录，并运行：

./out --config /var/lib/openlore/config/openlore.yml

这样可以让配置独立部署：简单部署可以将 openlore.yml 复制到卷上，而 Kubernetes 可以从 ConfigMap 投射同一个文件。对于 Fly.io、Railway、AWS、Google Cloud、Azure、DigitalOcean 或自定义基础设施，请使用 deploy 技能。仓库中的 Railpack 和 Fly 文件负责映像、持久卷和端口连线；它们不会在进程启动时预置或修改配置。

如需快速托管服务，而不创建自定义仓库，请使用部署到 Render按钮。与 Railpack 和 Fly 文件不同，它的启动脚本会在首次启动时将初始 openlore.yml 和 lore.json 写入空磁盘。Render 仅提供 HTTPS、MCP 和 Web 视图；它没有供 OpenLore SSH 使用的公共 TCP 入口。

Railway 会为其 SSH TCP 代理分配公共主机名和端口。标准 SSH 端口 22 需要外部原始 TCP 负载均衡器。Fly.io 可以通过专用地址将公共端口 22 映射到 OpenLore 的内部端口 2222。原始 SSH 不支持主机名或 SNI 路由，因此单个侦听器无法在端口 22 上路由多个域名。

容器工作流会从 main 发布 latest；发布版本还会发布 VERSION、vVERSION、主版本和次版本映像标签。

文档

相同页面会按相同分组发布在 openlore.sh/docs。

简介

页面	内容
什么是 OpenLore	在一个页面中提供服务、连接、限定范围、治理和观测
更新日志	当前版本、发布说明、兼容性说明和版本化文档

入门

页面	内容
快速入门	安装 OpenLore、提供文件夹服务，并连接 Agent
Claude Code	通过 MCP 连接 Claude Code，并限定其可查看的内容
Codex	通过 MCP 连接 Codex
Cursor	通过 MCP 连接 Cursor
OpenCode	通过 MCP 连接 OpenCode
Meta Muse	通过 MCP 连接 Meta Muse
OpenAI dots	通过 MCP 连接 OpenAI dots
Grok Bot	通过 MCP 连接 Grok Bot
Claude Duet	通过 MCP 连接 Claude Duet
LangChain	通过 MCP 连接 LangChain Agent，并为其设定身份
通过 SSH 连接任意 Agent	通过 SSH 连接编码 Agent 或 CI 作业，并为其设定身份

概念

了解 OpenLore 的工作方式：文档集、传输方式、身份、写入、规则和观察。

页面	内容
文档集	文档集的定义、围绕文档集组织访问的原因，以及嵌套、授权、别名和默认拒绝验证的工作方式
传输方式	SSH、SFTP、MCP、JSON API 和 Web 如何共享一个文件系统；MCP 工具、命令结果、会话和指令命令
身份验证	身份验证策略，以及 SSH 密钥、证书、通行密钥、OAuth 令牌和收件箱凭据如何解析为身份、角色、文档集、别名、主目录和工作负载身份联合
写入和发布	写入模式、收件箱、冲突处理、成功写入会检查和不会检查的内容，以及作业
文件夹规则	.lore/config.yaml 和 lore.json 规则、分层、权限、拒绝消息和增长限制
插件和格式	提供方接口、Open Knowledge Format 验证、lore validate、lore meta 和 Agent Skills 插件
仪表板和指标	仪表板身份验证、事实与活动的区别，以及文件查看器

操作指南

任务分步指南。

页面	内容
OpenLore 的使用方式	设置 SSH、通过 HTTP 和 stdio 使用 MCP、Web 视图、SSHFS、嵌入式二进制文件、GitHub Action、MCPB 和库的用法
配置服务	创建 openlore.yml、相对于嵌入式配置和标志的优先级、HTTPS、分析和调试日志
生产环境检查清单	共享服务在云端 Agent 可访问之前所需的配置：开箱即支持 HTTPS 的主机、固定在卷上的镜像、公共源站、/mcp 上的令牌、通行密钥
让 Agent 发布到收件箱	接受 Agent 的贡献，同时不允许其编辑其他任何内容
在编辑器中浏览和编辑	无需本地项目镜像，直接配置 VS Code 和 SFTP 编辑器
运行 headlong / shellm	通过 headlong 的 shellm 引擎使用 SSH 访问 OpenLore，包括其日常维护技能
从源代码构建	自行构建 Web UI 和二进制文件，或在不包含 Web UI 的情况下构建
将 OpenLore 部署到 Render	一键部署到 Render、首次使用通行密钥登录、升级和自定义域名

参考

查阅资料：命令、密钥、端点、接口和内部机制。

页面	内容
命令参考	完整的 shell、内省、发布、语法、CLI 命令和标志参考
openlore.yml 参考	openlore.yml 接受的所有键的生成式参考
规则标准库	内置规则成员及其参数的生成式参考
HTTP 收件箱 API	使用 bearer 或 HMAC 凭据的 POST /inbox/{docset}，以及令牌端点
OAuth 客户端	CIMD 客户端身份、private_key_jwt、mTLS 验证和签名密钥轮换
写入系统内部机制	文件系统分层、写入接缝、准入中间件和异步任务
构建仪表板	前端构建和仅构建后端的 Go 构建
安全评估	威胁模型和安全属性

安全

• 命令在纯 Go 解释器中运行，而非通过 os/exec 运行。
• 虚拟文件系统会清理路径并强制执行文档集边界。
• 允许的文件模式和忽略的目录可防止机密信息出现在视图中。
• RBAC 控制读取、发布、写入、审批和受信任的能力。
• Web 端点可通过 TLS 发布 SSH 主机密钥，以避免首次使用时盲目信任；也支持 SSH 用户证书和主机证书。

完整的安全评估请参阅 SECURITY.md。

许可证

Apache License 2.0 — 版权所有 © 2026 Adil Karim

OpenLore 捆绑了第三方开源组件。相关许可证和要求的声明列于 assets/legal/THIRD_PARTY_NOTICES.md，完整的许可证文本位于 assets/legal/licenses/。这些内容嵌入在二进制文件中，并由运行中的服务通过 /legal 提供。