OpenLore

将 OpenLore 指向一个包含 Markdown 的文件夹，你团队中的每个智能体都能读取相同的文件，无论是 Claude Code、Codex、Cursor 还是 CI 任务。智能体使用它们已经熟悉的工具，如 cat、grep 和 find。由你决定谁能查看和修改什么。

_{一键托管的服务器。参见 将 OpenLore 部署到 Render。}

快速开始

安装并提供一个文件夹：

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

SSH 运行在端口 2222 上。Web 视图和 MCP 共享端口 8080。./docs 的内容出现在 /。

连接一个智能体：

# 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' /"

告诉你的智能体何时使用它：

ssh -p 2222 localhost agents >> AGENTS.md

或者让你的智能体完成整个设置：

ssh openlore.sh teach | claude

没有使用 Homebrew？请参阅适用于 Linux 和 Windows 的 快速开始。

为什么不直接把 Markdown 放在你的仓库里？

对于单个仓库中的单个智能体，这样做是可以的。

OpenLore 适用于多个智能体、仓库或人员需要相同知识，并且你需要指定谁能读取、写入或发布什么内容的情况。一次更新文件，每个智能体在下次读取时都会看到新版本。

没有向量数据库、摄取管道或 SDK。你的知识保持为普通的 Markdown。

指南

• 什么是 OpenLore
• Claude Code
• Codex
• Cursor
• OpenCode
• 通过 SSH 使用任何智能体
• 让智能体发布到收件箱
• 部署到 Render
• 所有文档

功能

• 智能体原生检索 — 智能体使用它们已经理解的 shell 工具和组合模式，而不是学习一套专门的检索 API。
• 一个知识面，多种传输方式 — 通过 SSH、SFTP/SSHFS（包括直接通过 VS Code 浏览和编辑）、MCP 以及面向人类友好的 Web 视图提供相同的虚拟文件系统。
• 实时、受治理的知识 — 保持内容只读、允许有范围的发布，或按文档集启用完整写入。写入是原子的、冲突感知的，并在提交前经过验证。
• 身份范围视图 — 只给每个人或智能体提供其所需的文档集，并带有基于角色的 ro、publish 和 rw 授权、路径别名和私有主目录。
• 天生安全 — shell 是一个内存中的 Go 解释器，而不是真正的操作系统 shell。在正常会话中没有 shell 逃逸、任意进程执行或环境网络访问。
• 可移植的知识包 — 将文档嵌入到自包含的二进制文件中，使用 GitHub Action 构建跨平台包，或将它们打包为桌面 MCP 扩展。
• 无需新查询语言的结构化知识 — 使用 lore meta 将 frontmatter 检查为 NDJSON，使用 jq 查询它，并在接近写入路径处验证 Google 的 开放知识格式 (OKF) 包和 Agent Skills。
• 可扩展的策略和处理 — 插件可以添加验证、授权、读/写中间件、元数据和提交后处理，同时保持相同的文件系统接口。

使用场景

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

工作原理

OpenLore 基于 Wish 构建，用于 SSH 传输。连接完全在虚拟文件系统上处理：

1. 认证 — 无密钥连接或解析 SSH 密钥、证书、通行密钥或 OAuth 登录到身份。
2. 组合视图 — 只挂载授予该身份的文档集和路径。
3. 探索 — 运行作为纯 Go 函数实现的 shell 命令，或使用等效的 MCP shell 工具。
4. 安全贡献 — 如果启用了写入，在原子提交之前授权并验证整个文件的更改。

OAuth 客户端使用委派身份，因此持久的写入来源区分 adil 的直接工作和作为 adil/claude@claude.ai 执行的工作。委派者不能继承超过其主体的权限，并且可以通过文档集和能力拒绝列表进行缩小。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

参见 使用 OpenLore 的方式 了解直接 VS Code 编辑、MCP stdio、MCPB 桌面打包、SSHFS 和 Go 库用法。

创建定制部署

使用捆绑的 setup 技能创建 <team>-lore，一个小的客户拥有的仓库，包含 openlore.yml、一个固定到官方 OpenLore 版本的薄 Containerfile，以及部署工件。它构建一个可用的本地服务器，并在部署前验证 HTTP、MCP、认证 SSH、写入和持久性：

ssh openlore.sh setup | amp

生成的仓库将初始 lore.json 策略和 SSH 可见文件保存在 gitignored 的 .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 投影相同的文件。使用 deploy 技能用于 Fly.io、Railway、AWS、Google Cloud、Azure、DigitalOcean 或自定义基础设施。仓库的 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，提供文件夹服务，并连接代理
Claude Code	通过 MCP 连接 Claude Code 并限定其可见范围
Codex	通过 MCP 连接 Codex
Cursor	通过 MCP 连接 Cursor
OpenCode	通过 MCP 连接 OpenCode
通过 SSH 连接任意代理	通过 SSH 连接编码代理或 CI 任务，并为其分配身份

概念

OpenLore 的工作原理：文档集、传输方式、身份、写入、规则与观测。

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

操作指南

任务演练。

页面	内容
使用 OpenLore 的方式	设置 SSH、基于 HTTP 和 stdio 的 MCP、Web 视图、SSHFS、嵌入式二进制文件、GitHub Action、MCPB 和库用法
配置服务器	创建 openlore.yml，优先级高于嵌入式配置和标志、分析以及调试日志
让代理发布到收件箱	接受代理的贡献，而不让其编辑其他任何内容
从编辑器浏览和编辑	无需本地项目镜像，直接设置 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 提供。