OpenLore

Trỏ OpenLore vào một thư mục chứa Markdown và mọi tác nhân trong nhóm của bạn sẽ đọc cùng một tệp, dù đó là Claude Code, Codex, Cursor hay một tác vụ CI. Các tác nhân sử dụng những công cụ họ đã biết, như cat, grep và find. Bạn quyết định ai có thể xem và thay đổi nội dung gì.

_{Máy chủ lưu trữ một cú nhấp chuột. Xem Triển khai OpenLore lên Render.}

Bắt đầu nhanh

Cài đặt và phục vụ một thư mục:

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

SSH chạy trên cổng 2222. Chế độ xem web và MCP dùng chung cổng 8080. Nội dung của ./docs xuất hiện tại /.

Kết nối một tác nhân:

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

Hướng dẫn các tác nhân của bạn khi nào nên sử dụng:

ssh -p 2222 localhost agents >> AGENTS.md

Hoặc để tác nhân của bạn tự thực hiện toàn bộ thiết lập:

ssh openlore.sh teach | claude

Không dùng Homebrew? Xem Bắt đầu nhanh cho Linux và Windows.

Tại sao không chỉ giữ Markdown trong kho lưu trữ của bạn?

Với một tác nhân trong một kho lưu trữ, hãy làm điều đó.

OpenLore dành cho khi nhiều tác nhân, kho lưu trữ hoặc người dùng cần cùng một kiến thức và bạn cần xác định ai có thể đọc, ghi hoặc xuất bản nội dung gì. Cập nhật tệp một lần và mọi tác nhân sẽ thấy phiên bản mới ở lần đọc tiếp theo.

Không có cơ sở dữ liệu vector, quy trình nhập dữ liệu hay SDK. Kiến thức của bạn vẫn là Markdown thông thường.

Hướng dẫn

• OpenLore là gì
• Claude Code
• Codex
• Cursor
• OpenCode
• Bất kỳ tác nhân nào qua SSH
• Để tác nhân xuất bản vào hộp thư đến
• Triển khai lên Render
• Toàn bộ tài liệu

Tính năng

• Truy xuất thân thiện với tác nhân — Các tác nhân sử dụng các công cụ shell và mẫu tổ hợp mà họ đã hiểu thay vì học một API truy xuất riêng.
• Một bề mặt kiến thức, nhiều phương thức truyền tải — Phục vụ cùng một hệ thống tệp ảo qua SSH, SFTP/SSHFS (bao gồm duyệt và chỉnh sửa trực tiếp trong VS Code), MCP và chế độ xem web thân thiện với con người.
• Kiến thức trực tiếp, có kiểm soát — Giữ nội dung chỉ đọc, cho phép xuất bản có phạm vi hoặc bật ghi đầy đủ cho từng bộ tài liệu. Các thao tác ghi là nguyên tử, chống xung đột và được xác thực trước khi cam kết.
• Chế độ xem theo danh tính — Cấp cho mỗi người hoặc tác nhân chỉ những bộ tài liệu họ cần, với quyền dựa trên vai trò ro, publish và rw, bí danh đường dẫn và thư mục chính riêng tư.
• An toàn về mặt thiết kế — Shell là một trình thông dịch Go trong bộ nhớ, không phải shell hệ điều hành thực. Không có lỗ hổng shell, thực thi tiến trình tùy ý hoặc truy cập mạng ngầm trong phiên bình thường.
• Gói kiến thức di động — Nhúng tài liệu vào một tệp nhị phân độc lập, xây dựng gói đa nền tảng với GitHub Action hoặc đóng gói chúng dưới dạng tiện ích mở rộng MCP cho máy tính để bàn.
• Kiến thức có cấu trúc mà không cần ngôn ngữ truy vấn mới — Kiểm tra frontmatter dưới dạng NDJSON với lore meta, truy vấn bằng jq và xác thực các gói Open Knowledge Format (OKF) của Google và Agent Skills gần đường ghi.
• Chính sách và xử lý mở rộng — Plugin có thể thêm xác thực, quyền, middleware đọc/ghi, siêu dữ liệu và xử lý sau cam kết trong khi vẫn giữ nguyên giao diện hệ thống tệp.

Trường hợp sử dụng

• Kho học tập liên tục — lưu trữ các phiên và bài học trong một máy chủ dùng chung. Thêm số liệu để tối ưu hóa. Cho phép các tác nhân chia sẻ bài học với nhau trong khi vẫn duy trì sự cô lập người dùng.
• Kho lưu trữ tạo phẩm của nhóm — chia sẻ các tài liệu markdown, HTML, JSON, Excel, v.v. bạn đã tạo trong khi vẫn duy trì kiểm soát truy cập. Tự nhiên hơn nhiều so với git, thân thiện với tác nhân hơn Confluence/Notion.
• Tài liệu cho tác nhân mã hóa — Đặt tài liệu API nội bộ, sổ tay vận hành, bối cảnh sản phẩm và ghi chú kiến trúc sau một giao diện quen thuộc, có thể tìm kiếm.
• Bộ nhớ trực tiếp dùng chung cho nhóm tác nhân — Cấp cho các tác nhân các bộ tài liệu riêng hoặc dùng chung để họ có thể xuất bản phát hiện, bàn giao công việc và tích lũy bối cảnh bền vững qua các phiên.
• Trang tài liệu công khai — thêm bất kỳ tệp nào vào bộ tài liệu công khai của bạn, bật truy cập công khai và nó sẽ được hiển thị cho bất kỳ tác nhân nào tình cờ truy cập trang của bạn. Cải thiện AEO/GEO mà không cần chỉnh sửa tài liệu hiện có.
• Chia sẻ kỹ năng — Xuất bản Agent Skills vào các bộ sưu tập dùng chung để mọi tác nhân được ủy quyền có thể khám phá và sử dụng cùng các quy trình có kiểm soát.
• Kho plugin tác nhân — Khóa phiên bản các kho Agent Plugins từ GitHub và phục vụ chúng cho các tác nhân trong nhóm. Các kỹ năng được đóng gói theo tiêu chuẩn mở sẽ tự động cập nhật.
• Đóng góp kiến thức có kiểm soát — Cho phép người đóng góp xuất bản vào hộp thư đến trong khi dành các tài liệu hiện có cho người duy trì và ngăn chặn ghi đè vô tình.
• Kho tạo phẩm — Lưu trữ và hiển thị báo cáo, nhật ký, ảnh chụp màn hình và tệp đã tạo qua trình duyệt hoặc SSH mà không cần xây dựng trình xem tạo phẩm tùy chỉnh hoặc cấp quyền truy cập vào máy của tác nhân.
• Không gian làm việc theo danh tính — Gắn một thư mục chính riêng cho mỗi tác nhân cùng với kiến thức nhóm dùng chung, tất cả qua một máy chủ và một mô hình ủy quyền.
• Kiến thức khách hàng hoặc dự án di động — Gửi một tệp thực thi có phiên bản với tài liệu liên quan được nhúng hoặc phân phối cùng kiến thức dưới dạng tiện ích mở rộng máy tính để bàn MCPB.
• Danh mục kiến thức đã xác thực — Thực thi các quy ước frontmatter và gói, kiểm tra siêu dữ liệu một cách rẻ và chặn kiến thức sai định dạng ngay khi tiếp nhận.

Cách hoạt động

OpenLore được xây dựng trên Wish cho truyền tải SSH. Một kết nối được xử lý hoàn toàn dựa trên hệ thống tệp ảo:

1. Xác thực — kết nối không cần khóa hoặc phân giải khóa SSH, chứng chỉ, passkey hoặc đăng nhập OAuth thành một danh tính.
2. Tạo chế độ xem — gắn chỉ các bộ tài liệu và đường dẫn được cấp cho danh tính đó.
3. Khám phá — chạy các lệnh shell được triển khai dưới dạng hàm Go thuần túy trên chế độ xem đó hoặc sử dụng công cụ MCP shell tương đương.
4. Đóng góp an toàn — nếu ghi được bật, hãy ủy quyền và xác thực thay đổi toàn bộ tệp trước khi cam kết nguyên tử.

Các máy khách OAuth sử dụng danh tính được ủy quyền, vì vậy nguồn gốc ghi bền vững phân biệt công việc trực tiếp của adil với công việc được thực hiện với tư cách adil/claude@claude.ai. Người được ủy quyền không thể kế thừa quyền hạn nhiều hơn người ủy quyền chính và có thể bị thu hẹp theo danh sách từ chối bộ tài liệu và khả năng. Máy khách CIMD cũng có thể xác thực bằng siêu dữ liệu do nhà cung cấp lưu trữ và private_key_jwt; xem Máy khách OAuth đã xác thực.

Shell thông thường không thể gọi bash, exec, curl hoặc các tiến trình máy chủ tùy ý. Tài liệu nhúng luôn chỉ đọc. Các danh tính được tin cậy rõ ràng có thể được cấp xử lý bất đồng bộ có phạm vi hẹp thông qua khả năng spawn.

Ghi có kiểm soát

OpenLore chỉ đọc theo mặc định. Các triển khai cho phép ghi giữ một đường ghi duy nhất, có kiểm soát chính sách cho chuyển hướng, nối thêm, tee, patch, sed -i, di chuyển tệp, xuất bản và các công việc bên ngoài đáng tin cậy.

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

Các thao tác ghi là các hoán đổi nguyên tử toàn bộ đối tượng. Bảo vệ so sánh-và-hoán đổi từ chối các chỉnh sửa lỗi thời theo mặc định, quyền bộ tài liệu giới hạn mục tiêu và plugin có thể xác thực hoặc hoãn ghi trước khi cam kết.

Xem Ghi và xuất bản để thiết lập hướng người dùng và Nội bộ hệ thống ghi cho mô hình triển khai.

Cài đặt

Xem Bắt đầu nhanh cho các bản phát hành Homebrew, Linux và Windows, và các bản cài đặt nào bao gồm bảng điều khiển. Để tự xây dựng OpenLore, xem Xây dựng từ mã nguồn.

Nhúng tài liệu vào tệp nhị phân

Đặt tài liệu vào assets/lore/ và xây dựng. Tệp nhị phân kết quả chứa tài liệu và phục vụ chúng ở chế độ chỉ đọc tại /docs khi chạy mà không có đối số thư mục:

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

Xây dựng với GitHub Action

Tạo các tệp nhị phân đa nền tảng với tài liệu của bạn được nhúng:

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

Xem Các cách sử dụng OpenLore để chỉnh sửa trực tiếp trong VS Code, MCP stdio, đóng gói MCPB cho máy tính để bàn, SSHFS và cách sử dụng thư viện Go.

Tạo triển khai tùy chỉnh

Sử dụng kỹ năng setup đi kèm để tạo <team>-lore, một kho lưu trữ nhỏ do khách hàng sở hữu chứa openlore.yml, một Containerfile mỏng được khóa vào một bản phát hành OpenLore chính thức và các tạo phẩm triển khai. Nó xây dựng một máy chủ cục bộ hoạt động và xác minh HTTP, MCP, SSH đã xác thực, ghi và lưu trữ bền vững trước khi triển khai:

ssh openlore.sh setup | amp

Kho lưu trữ được tạo giữ chính sách lore.json ban đầu và các tệp hiển thị qua SSH dưới .local/ được gitignore. Lần triển khai đầu tiên khởi tạo một ổ đĩa bền vững trống từ trạng thái đó. openlore.yml gốc vẫn là cơ quan Git/IaC và được triển khai riêng tới /var/lib/openlore/config/openlore.yml; nó không được nhúng vào hình ảnh. Các chỉnh sửa lore.json và hệ thống tệp sau đó trên máy chủ là có thẩm quyền và không bao giờ bị ghi đè bởi các bản cập nhật hình ảnh.

Các lệnh hướng dẫn bổ sung hỗ trợ toàn bộ vòng đời:

• onboarding thêm danh tính, vai trò, thư mục chính và thư mục ban đầu cục bộ;
• deploy chọn Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean hoặc triển khai tùy chỉnh và xác minh hợp đồng lưu trữ/mạng dùng chung;
• upgrade chỉ chuẩn bị thay đổi phiên bản hình ảnh cơ sở được khóa để CD hiện có có thể triển khai.

Triển khai nhà cung cấp yêu cầu HTTPS/MCP, SSH OpenLore đã xác thực, quyền truy cập shell quản trị và ổ đĩa /var/lib/openlore bền vững. Nơi nhà cung cấp hỗ trợ, triển khai cấu hình cổng công khai 22 chuyển tiếp tới cổng OpenLore 2222. Nếu không, nó báo cáo cổng được chỉ định và đề xuất hệ thống chuyển tiếp TCP bên ngoài.

Container được xuất bản chỉ chứa OpenLore. Nó cố tình không chứa chính sách gia nhập hoặc cấu hình máy chủ. Trước khi dịch vụ khởi động, triển khai phải đặt openlore.yml và lore.json vào thư mục cấu hình bền vững và chạy:

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

Điều này giữ cấu hình có thể triển khai độc lập: một triển khai đơn giản có thể sao chép openlore.yml vào ổ đĩa, trong khi Kubernetes có thể chiếu cùng tệp từ ConfigMap. Sử dụng kỹ năng deploy cho Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean hoặc cơ sở hạ tầng tùy chỉnh. Các tệp Railpack và Fly của kho lưu trữ cung cấp hình ảnh, ổ đĩa bền vững và kết nối cổng; chúng không gieo hoặc sửa đổi cấu hình khi khởi động tiến trình.

Để có máy chủ lưu trữ nhanh mà không cần kho lưu trữ tùy chỉnh, hãy sử dụng nút Triển khai lên Render. Không giống như các tệp Railpack và Fly, tập lệnh khởi động của nó ghi một openlore.yml và lore.json khởi đầu vào một ổ đĩa trống ở lần khởi động đầu tiên. Render phục vụ HTTPS, MCP và chế độ xem web; nó không có cổng vào TCP công khai cho SSH OpenLore.

Railway gán cho proxy TCP SSH của nó một tên máy chủ và cổng công khai. Cổng SSH chuẩn 22 yêu cầu bộ cân bằng tải TCP thô bên ngoài. Fly.io có thể ánh xạ cổng công khai 22 tới cổng nội bộ 2222 của OpenLore với một địa chỉ chuyên dụng. SSH thô không có định tuyến tên máy chủ hoặc SNI, vì vậy một trình nghe không thể định tuyến nhiều miền trên cổng 22.

Quy trình container xuất bản latest từ main; các bản phát hành cũng xuất bản VERSION, vVERSION, các thẻ hình ảnh chính và phụ.

Tài liệu

Các trang tương tự, trong cùng các nhóm, được xuất bản tại openlore.sh/docs.

Giới thiệu

Trang	Nội dung
OpenLore là gì	Phục vụ, kết nối, phạm vi, kiểm soát và quan sát trong một trang
Nhật ký thay đổi	Phiên bản hiện tại, ghi chú phát hành, ghi chú tương thích và tài liệu theo phiên bản

Bắt đầu

Trang	Nội dung
Khởi động nhanh	Cài đặt OpenLore, phục vụ một thư mục và kết nối một tác nhân
Claude Code	Kết nối Claude Code qua MCP và giới hạn phạm vi nó có thể thấy
Codex	Kết nối Codex qua MCP
Cursor	Kết nối Cursor qua MCP
OpenCode	Kết nối OpenCode qua MCP
Bất kỳ tác nhân nào qua SSH	Kết nối một tác nhân lập trình hoặc công việc CI qua SSH và cấp cho nó một danh tính

Khái niệm

Cách OpenLore hoạt động: docset, phương thức truyền tải, danh tính, ghi, quy tắc và quan sát.

Trang	Nội dung
Docset	Docset là gì, tại sao quyền truy cập được tổ chức xung quanh chúng, và cách hoạt động của lồng nhau, cấp quyền, bí danh và xác thực đóng theo chế độ fail-closed
Phương thức truyền tải	Cách SSH, SFTP, MCP, JSON API và web chia sẻ một hệ thống tệp, các công cụ MCP, kết quả lệnh, phiên và lệnh hướng dẫn
Xác thực	Tư thế xác thực, cách khóa SSH, chứng chỉ, passkey, mã thông báo OAuth và thông tin xác thực hộp thư đến phân giải thành danh tính, vai trò, docset, bí danh, thư mục chính và liên kết danh tính khối lượng công việc
Ghi và xuất bản	Chế độ ghi, hộp thư đến, xử lý xung đột, những gì một lần ghi thành công kiểm tra và không kiểm tra, và các công việc
Quy tắc thư mục	Quy tắc .lore/config.yaml và lore.json, phân lớp, quyền, thông báo từ chối và giới hạn tăng trưởng
Plugin và định dạng	Giao diện nhà cung cấp, xác thực Định dạng Kiến thức Mở, lore validate, lore meta và plugin Kỹ năng Tác nhân
Bảng điều khiển và số liệu	Xác thực bảng điều khiển, sự kiện so với hoạt động và trình xem tệp

Cách thực hiện

Hướng dẫn từng bước cho các tác vụ.

Trang	Nội dung
Các cách sử dụng OpenLore	Thiết lập SSH, MCP qua HTTP và stdio, chế độ xem web, SSHFS, tệp nhúng, GitHub Action, MCPB và cách sử dụng thư viện
Cấu hình máy chủ	Tạo openlore.yml, ưu tiên so với cấu hình nhúng và cờ, phân tích và ghi nhật ký gỡ lỗi
Cho phép tác nhân xuất bản vào hộp thư đến	Chấp nhận đóng góp từ một tác nhân mà không cho nó chỉnh sửa bất kỳ thứ gì khác
Duyệt và chỉnh sửa từ trình soạn thảo	Thiết lập trực tiếp VS Code và trình soạn thảo SFTP mà không cần bản sao dự án cục bộ
Chạy headlong / shellm	Sử dụng OpenLore qua SSH từ công cụ shellm của headlong, bao gồm kỹ năng bảo trì của nó
Xây dựng từ mã nguồn	Tự xây dựng giao diện web và tệp nhị phân, hoặc xây dựng không có giao diện web
Triển khai OpenLore lên Render	Triển khai Render một cú nhấp chuột, đăng nhập passkey đầu tiên, nâng cấp và tên miền tùy chỉnh

Tham khảo

Tài liệu tra cứu: lệnh, khóa, điểm cuối, giao diện và nội bộ.

Trang	Nội dung
Tham chiếu lệnh	Tham chiếu đầy đủ về shell, nội quan, xuất bản, cú pháp, lệnh CLI và cờ
Tham chiếu openlore.yml	Tham chiếu được tạo cho mọi khóa openlore.yml chấp nhận
Thư viện chuẩn quy tắc	Tham chiếu được tạo cho các thành viên quy tắc được biên dịch sẵn và tham số của chúng
API hộp thư đến HTTP	POST /inbox/{docset} với thông tin xác thực bearer hoặc HMAC và các điểm cuối mã thông báo
Máy khách OAuth	Danh tính máy khách CIMD, private_key_jwt, xác thực bổ sung mTLS và xoay khóa ký
Nội bộ hệ thống ghi	Phân lớp hệ thống tệp, đường nối ghi, phần mềm trung gian tiếp nhận và công việc không đồng bộ
Xây dựng bảng điều khiển	Xây dựng giao diện người dùng và bản dựng Go chỉ dành cho backend
Đánh giá bảo mật	Mô hình mối đe dọa và thuộc tính bảo mật

Bảo mật

• Các lệnh chạy trong trình thông dịch Go thuần túy, không qua os/exec.
• Hệ thống tệp ảo làm sạch đường dẫn và thực thi ranh giới docset.
• Các mẫu tệp được phép và thư mục bị bỏ qua giữ bí mật ngoài tầm nhìn.
• RBAC kiểm soát đọc, xuất bản, ghi, phê duyệt và các khả năng đáng tin cậy.
• Điểm cuối web có thể xuất bản khóa máy chủ SSH qua TLS để tránh tin tưởng mù khi sử dụng lần đầu; chứng chỉ người dùng và máy chủ SSH cũng được hỗ trợ.

Xem SECURITY.md để biết đánh giá bảo mật đầy đủ.

Giấy phép

Giấy phép Apache 2.0 — Bản quyền © 2026 Adil Karim

OpenLore đi kèm các thành phần mã nguồn mở của bên thứ ba. Giấy phép và thông báo bắt buộc của chúng được liệt kê trong assets/legal/THIRD_PARTY_NOTICES.md, với văn bản giấy phép đầy đủ trong assets/legal/licenses/. Các tệp này được nhúng trong tệp nhị phân và được phục vụ bởi dịch vụ đang chạy tại /legal.