OpenLore

📜 OpenLore

Disponsori oleh

Sajikan dokumentasi Anda kepada agen AI melalui SSH.

OpenLore adalah basis pengetahuan minimal, dapat diperluas, dan ramah-agen yang menjaga konteks bersama tetap terkini dan dapat diperiksa.

---

Tentang

Agen pengkode AI sudah tahu cara menjelajahi file dengan ls, cat, grep, find, pipa, dan loop shell. OpenLore memberi mereka antarmuka yang sama melalui SSH, didukung oleh dokumentasi Anda alih-alih mesin sungguhan.

Agent ──SSH or MCP──▶ OpenLore ──▶ docs, knowledge, and artifacts

Ini dimulai sebagai server dokumentasi biner tunggal, tanpa konfigurasi, dan hanya-baca. Ketika Anda membutuhkan basis pengetahuan langsung, Anda dapat menambahkan akses terbatas identitas, penerbitan terkontrol, penulisan atomik, validasi, dan persetujuan manusia tanpa mengubah cara agen membaca atau menavigasi konten.

Simpan dan ambil Markdown

Letakkan dokumentasi, runbook, konteks proyek, atau catatan yang ditulis agen dalam file Markdown biasa. Tidak ada jalur ingest: arahkan OpenLore ke direktori dan ia menyajikan hierarki yang ada secara langsung. Atur dokumen dengan folder, hubungkan dengan tautan Markdown standar, dan kelompokkan ke dalam docset ketika orang atau agen yang berbeda membutuhkan akses yang berbeda. OpenLore hanya-baca secara default; aktifkan penulisan ketika Anda ingin agen membuat dan memperbarui Markdown juga.

Mulai Cepat

Jalur tercepat adalah membiarkan agen Anda menyiapkan OpenLore:

# Teach your agent how to install, configure, and bundle OpenLore
ssh openlore.sh teach | your-agent-cli

# Add documentation access instructions to AGENTS.md
ssh openlore.sh agents >> AGENTS.md

Atau instal dan jalankan secara langsung:

go install github.com/aakarim/go-openlore/cmd/openlore@latest

openlore ./docs

ssh -p 2222 localhost
ssh -p 2222 localhost "grep -r 'authentication' /docs"

Secara default ini memulai:

• SSH pada localhost:2222
• tampilan web untuk manusia pada http://localhost:8080
• MCP melalui HTTP pada http://localhost:8080/mcp

Lihat Instalasi untuk lebih banyak cara menginstal dan mengemas OpenLore.

Fitur

• Pengambilan ramah-agen — Agen menggunakan alat shell dan pola komposisi yang sudah mereka pahami alih-alih mempelajari API pengambilan khusus.
• Satu permukaan pengetahuan, banyak transport — Sajikan sistem file virtual yang sama melalui SSH, SFTP/SSHFS, MCP, dan tampilan web yang ramah manusia.
• Pengetahuan langsung dan terkelola — Jaga konten hanya-baca, izinkan penerbitan terbatas, atau aktifkan penulisan penuh per docset. Penulisan bersifat atomik, sadar-konflik, dan dapat memerlukan persetujuan manusia.
• Tampilan terbatas identitas — Berikan setiap orang atau agen hanya docset yang dibutuhkannya, dengan hibah berbasis peran ro, publish, dan rw, alias jalur, dan direktori rumah pribadi.
• Aman secara desain — Shell adalah interpreter Go dalam memori, bukan shell sistem operasi sungguhan. Tidak ada pelarian shell, eksekusi proses arbitrer, atau akses jaringan ambien dalam sesi normal.
• Paket pengetahuan portabel — Sematkan dokumen ke dalam biner mandiri, bangun paket lintas platform dengan GitHub Action, atau kemas sebagai ekstensi MCP desktop.
• Pengetahuan terstruktur tanpa bahasa kueri baru — Periksa frontmatter sebagai NDJSON dengan lore meta, kueri dengan jq, dan validasi Open Knowledge Format (OKF) Google dan bundle Agent Skills dekat dengan jalur penulisan.
• Kebijakan dan pemrosesan yang dapat diperluas — Plugin dapat menambahkan validasi, hibah, middleware baca/tulis, metadata, dan pemrosesan pasca-komit sambil mempertahankan antarmuka sistem file yang sama.

Kasus Penggunaan

• Repositori Pembelajaran Berkelanjutan - simpan sesi dan pembelajaran dalam satu server bersama. Tambahkan metrik sehingga Anda dapat mengoptimalkan. Izinkan agen berbagi pembelajaran satu sama lain sambil menjaga isolasi pengguna.
• Repositori Artefak Tim - bagikan dokumen markdown, HTML, JSON, Excel, dll. yang telah Anda buat sambil menjaga kontrol akses. Jauh lebih alami daripada git, lebih ramah-agen daripada Confluence/Notion.
• Dokumentasi untuk agen pengkode — Letakkan dokumentasi API internal, runbook, konteks produk, dan catatan arsitektur di belakang antarmuka yang familier dan dapat dicari.
• Memori langsung bersama untuk tim agen — Berikan agen docset terpisah atau bersama sehingga mereka dapat memublikasikan temuan, menyerahkan pekerjaan, dan mengumpulkan konteks tahan lama lintas sesi.
• Situs dokumentasi publik - tambahkan file apa pun ke docset publik Anda, aktifkan akses publik dan itu akan ditampilkan ke agen mana pun yang menemukan situs Anda. Meningkatkan AEO/GEO tanpa perlu mengedit dokumentasi yang ada.
• Berbagi keterampilan — Publikasikan Agent Skills ke dalam koleksi bersama sehingga setiap agen yang berwenang dapat menemukan dan menggunakan prosedur terkelola yang sama.
• Repositori Plugin Agen — Kunci versi repositori Agent Plugins dari GitHub dan sajikan ke agen tim Anda. Keterampilan yang dikemas dalam standar terbuka tetap terkini secara otomatis.
• Kontribusi pengetahuan terkelola — Izinkan kontributor memublikasikan ke kotak masuk sambil mencadangkan jalur sensitif untuk penyetuju dan mencegah penimpaan yang tidak disengaja.
• Tinjauan jarak jauh artefak agen — Ekspos laporan, log, tangkapan layar, dan file yang dihasilkan melalui browser atau SSH tanpa membangun penampil artefak khusus atau memberikan akses ke mesin agen.
• Ruang kerja khusus identitas — Pasang rumah pribadi untuk setiap agen plus pengetahuan tim bersama, semuanya melalui satu server dan satu model otorisasi.
• Pengetahuan pelanggan atau proyek portabel — Kirim executable berversi dengan dokumen relevan yang disematkan, atau distribusikan pengetahuan yang sama sebagai ekstensi desktop MCPB.
• Katalog pengetahuan tervalidasi — Terapkan konvensi frontmatter dan bundle, periksa metadata dengan murah, dan hentikan pengetahuan yang salah format pada saat penerimaan.

Cara Kerjanya

OpenLore dibangun di atas Wish untuk transport SSH. Koneksi ditangani sepenuhnya terhadap sistem file virtual:

1. Autentikasi — hubungkan tanpa kunci atau selesaikan kunci SSH, sertifikat, passkey, atau login OAuth menjadi identitas.
2. Susun tampilan — pasang hanya docset dan jalur yang diberikan kepada identitas itu.
3. Jelajahi — jalankan perintah shell yang diimplementasikan sebagai fungsi Go murni atas tampilan itu, atau gunakan alat MCP shell yang setara.
4. Berkontribusi dengan aman — jika penulisan diaktifkan, otorisasi dan validasi perubahan seluruh file sebelum mengkomitnya secara atomik atau merutekannya untuk persetujuan.

Klien OAuth menggunakan identitas yang didelegasikan, sehingga provenans penulisan yang tahan lama membedakan pekerjaan langsung oleh adil dari pekerjaan yang dilakukan sebagai adil/claude@claude.ai. Delegasi tidak dapat mewarisi otoritas lebih dari prinsipalnya dan dapat dipersempit oleh docset dan daftar penolakan kemampuan. Klien CIMD juga dapat mengautentikasi dengan metadata yang dihosting vendor dan private_key_jwt; lihat Klien OAuth Terautentikasi.

Shell normal tidak dapat memanggil bash, exec, curl, atau proses host arbitrer. Dokumentasi yang disematkan selalu hanya-baca. Identitas yang dipercaya secara eksplisit dapat diberikan pemrosesan asinkron yang dibatasi sempit melalui kemampuan spawn.

Penulisan Terkelola

OpenLore hanya-baca secara default. Penerapan yang dapat ditulis menjaga satu jalur penulisan yang dikendalikan kebijakan untuk pengalihan, penambahan, tee, patch, sed -i, pemindahan file, penerbitan, dan pekerjaan eksternal yang disetujui.

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

Penulisan adalah pertukaran atomik seluruh objek. Perlindungan bandingkan-dan-tukar menolak edit basi secara default, hibah docset membatasi target, dan jalur yang dipilih dapat menghasilkan perubahan yang dapat ditinjau di bawah /requests alih-alih mengkomit langsung.

Lihat Menulis dan menerbitkan untuk pengaturan yang menghadap pengguna dan Internal sistem penulisan untuk model implementasi.

Instalasi

Instal dengan Go

Membutuhkan Go 1.26 atau lebih baru:

go install github.com/aakarim/go-openlore/cmd/openlore@latest

Bangun dari sumber

git clone https://github.com/aakarim/go-openlore.git
cd go-openlore
go build -o openlore ./cmd/openlore

Sematkan dokumen dalam biner

Letakkan dokumentasi di assets/lore/ dan bangun. Biner yang dihasilkan berisi dokumen dan menyajikannya hanya-baca di /docs ketika dijalankan tanpa argumen direktori:

go build -o my-docs ./cmd/openlore

Bangun dengan GitHub Action

Hasilkan biner lintas platform dengan dokumen Anda disematkan:

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

Lihat Cara menggunakan OpenLore untuk MCP stdio, pengemasan desktop MCPB, SSHFS, dan penggunaan pustaka Go.

Buat penerapan yang disesuaikan

Gunakan keterampilan setup yang disertakan untuk membuat <team>-lore, repositori kecil milik pelanggan yang berisi openlore.yml, Containerfile tipis yang dipatok ke rilis OpenLore resmi, dan artefak penerapan. Ini membangun server lokal yang berfungsi dan memverifikasi HTTP, MCP, SSH terautentikasi, penulisan, dan persistensi sebelum penerapan:

ssh openlore.sh setup | amp

Repositori yang dihasilkan menjaga kebijakan lore.json awal dan file yang terlihat SSH di bawah .local/ yang diabaikan git. Penerapan pertama menginisialisasi volume persisten kosong dari keadaan itu. openlore.yml root tetap menjadi otoritas Git/IaC dan diterapkan secara terpisah ke /var/lib/openlore/config/openlore.yml; itu tidak dipanggang ke dalam gambar. lore.json dan edit sistem file di server kemudian bersifat otoritatif dan tidak pernah ditimpa oleh pembaruan gambar.

Perintah instruksi tambahan mendukung siklus hidup penuh:

• onboarding menambahkan identitas, peran, rumah, dan folder awal secara lokal;
• deploy memilih Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean, atau penerapan khusus dan memverifikasi kontrak persistensi/jaringan bersama;
• upgrade menyiapkan hanya perubahan versi gambar dasar yang dipatok sehingga CD yang ada dapat menerapkannya.

Penerapan penyedia memerlukan HTTPS/MCP, SSH OpenLore terautentikasi, akses shell administratif, dan volume /var/lib/openlore persisten. Di mana penyedia mendukungnya, penerapan mengonfigurasi port publik 22 untuk meneruskan ke port OpenLore 2222. Jika tidak, ia melaporkan port yang ditetapkan dan merekomendasikan sistem penerusan TCP eksternal.

Kontainer yang diterbitkan hanya berisi OpenLore. Ia sengaja tidak berisi kebijakan orientasi atau konfigurasi server. Sebelum layanan dimulai, penerapan harus menempatkan openlore.yml dan lore.json di direktori konfigurasi persisten dan menjalankan:

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

Ini menjaga konfigurasi dapat diterapkan secara independen: penerapan sederhana dapat menyalin openlore.yml ke volume, sementara Kubernetes dapat memproyeksikan file yang sama dari ConfigMap. Gunakan keterampilan deploy untuk Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean, atau infrastruktur khusus. File Railpack dan Fly repositori menyediakan gambar, volume persisten, dan kabel port; mereka tidak menyemai atau mengubah konfigurasi saat proses dimulai.

Railway menetapkan proxy TCP SSH-nya nama host dan port publik. Port SSH standar 22 memerlukan penyeimbang beban TCP mentah eksternal. Fly.io dapat memetakan port publik 22 ke port internal OpenLore 2222 dengan alamat khusus. SSH mentah tidak memiliki nama host atau perutean SNI, jadi satu pendengar tidak dapat merutekan beberapa domain di port 22.

Alur kerja kontainer menerbitkan latest dari main; rilis juga menerbitkan tag gambar VERSION, vVERSION, mayor, dan minor.

Unggahan kotak masuk HTTP

Konfigurasikan docset inbox dan peran dengan hibah publish-nya, lalu buat kredensial untuk identitas yang ada (konfigurasi server harus menyebutkan auth_file sehingga CLI dapat memvalidasinya):

openlore inbox token create --identity alice --label webhook --config openlore.yml
curl -H 'Authorization: Bearer olin_ID_SECRET' -H 'Content-Type: text/markdown' \
  --data-binary @note.md 'https://docs.example.com/inbox/docs?name=note.md'

POST /inbox/{docset} menerima kredensial pembawa atau HMAC badan persis menggunakan X-OpenLore-Token-Id dan X-OpenLore-Signature. Token akses OAuth digunakan hanya untuk POST/GET /inbox/tokens dan DELETE /inbox/tokens/{id}; kredensial kotak masuk terpisah dan dapat dicabut. Lihat Konfigurasi dan identitas.

Dokumentasi

Panduan	Isi
Cara menggunakan OpenLore	SSH, MCP, web, SSHFS, biner tertanam, GitHub Action, MCPB, dan penggunaan pustaka
Referensi perintah	Referensi lengkap shell, introspeksi, penerbitan, sintaks, perintah CLI, dan flag
Konfigurasi dan identitas	openlore.yml, autentikasi, peran, docset, alias, home, dan verifikasi host
Federasi identitas beban kerja	Autentikasi CI dan agen dengan token identitas eksternal berumur pendek
Menulis dan menerbitkan	Mode tulis, kotak masuk, penanganan konflik, persetujuan, dan pekerjaan
Plugin dan format pengetahuan	Instalasi plugin, antarmuka, validasi OKF, lore validate, dan lore meta
Internal sistem tulis	Pelapisan sistem file, jahitan tulis, perubahan, hook, dan pekerjaan asinkron
Evaluasi keamanan	Model ancaman dan properti keamanan

Keamanan

• Perintah dijalankan dalam interpreter Go murni, bukan melalui os/exec.
• Sistem file virtual membersihkan jalur dan menegakkan batas docset.
• Pola file yang diizinkan dan direktori yang diabaikan menjaga rahasia dari tampilan.
• RBAC mengontrol pembacaan, penerbitan, penulisan, persetujuan, dan kemampuan tepercaya.
• Titik akhir web dapat menerbitkan kunci host SSH melalui TLS untuk menghindari kepercayaan buta pada penggunaan pertama; sertifikat pengguna dan host SSH juga didukung.

Lihat SECURITY.md untuk evaluasi keamanan lengkap.

Lisensi

MIT — Adil Karim

OpenLore menggabungkan komponen sumber terbuka pihak ketiga. Lisensi dan pemberitahuan yang diperlukan tercantum di assets/legal/THIRD_PARTY_NOTICES.md, dengan teks lisensi lengkap di assets/legal/licenses/. Ini tertanam dalam biner dan dilayani oleh layanan yang berjalan di /legal.