Skip to content
Back to search

OpenLore

A minimal, extensible, agent-native knowledge repository that keeps shared context current and inspectable

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/aakarim/OpenLore with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/aakarim/OpenLore'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aakarim--openlore/badge.svg)](/listings/aakarim--openlore)

HTML

<a href="/listings/aakarim--openlore"><img src="/api/listings/aakarim--openlore/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install and serve a folder:

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

SSH runs on port `2222`. The web view and MCP share port `8080`. The contents of `./docs` appear at `/`.

Connect an 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' /"

Tell your agents when to use it:

ssh -p 2222 localhost agents >> AGENTS.md

Or let your agent do the whole setup:

ssh openlore.sh teach | claude

Not on Homebrew? See the [Quickstart](docs/quickstart.md#install) for Linux and Windows.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 388 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # 📜 OpenLore
  3. [![Release](https://img.shields.io/github/v/release/aakarim/OpenLore)](https://github.com/aakarim/OpenLore/releases/latest)
  4. [![Go Reference](https://pkg.go.dev/badge/github.com/aakarim/go-openlore.svg)](https://pkg.go.dev/github.com/aakarim/go-openlore)
  5. <a href="https://trendshift.io/repositories/85262?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-85262" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/85262/daily?language=Go" alt="aakarim%2FOpenLore | Trendshift" width="250" height="55"/></a>
  6. Sponsored by <a href="https://oiya.ai/?utm_source=github&amp;utm_medium=referral&amp;utm_campaign=openlore&amp;utm_content=sponsor_logo"><img src="assets/oiya-logo.svg" alt="Oiya" height="24" align="absmiddle"></a>
  7. **Give every AI agent on your team the same up-to-date knowledge.**
  8. </div>
  9. Point OpenLore at a folder of Markdown and every agent on your team reads the same files, whether it's Claude Code, Codex, Cursor or a CI job. Agents use the tools they already know, like `cat`, `grep` and `find`. You decide who can see and change what.
  10. <p align="center">
  11. <a href="https://render.com/deploy?repo=https://github.com/aakarim/OpenLore"><img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render"></a>
  12. <br>
  13. <sub>One-click hosted server. See <a href="docs/how-to/deploy/render.md">Deploy OpenLore to Render</a>.</sub>
  14. </p>
  15. <p align="center">
  16. <img src="assets/openlore-how-it-works.svg" alt="Claude Code, Codex and a CI job connect to one OpenLore server, which checks each identity's access and serves the same folder of Markdown" width="820">
  17. </p>
  18. ## Quick start
  19. Install and set up a knowledge repository for your team:
  20. ```shell
  21. brew install --cask aakarim/tap/lore
  22. lore init my-knowledge
  23. cd my-knowledge
  24. ```
  25. `lore init` creates the folder and an `openlore.yml` with default server settings.
  26. Already in your knowledge repository? Run `lore init` without a directory.
  27. Put your Markdown in a `docs/` folder inside the repository, then serve it:
  28. ```shell
  29. openlore ./docs
  30. ```
  31. SSH runs on port `2222`. The web view and MCP share port `8080`. The contents of `./docs` appear at `/`.
  32. Connect an agent:
  33. ```shell
  34. # Claude Code
  35. claude mcp add --transport http openlore http://localhost:8080/mcp
  36. # Codex
  37. codex mcp add openlore --url http://localhost:8080/mcp
  38. # Anything with a shell
  39. ssh -p 2222 localhost "grep -r 'retry' /"
  40. ```
  41. Tell your agents when to use it:
  42. ```shell
  43. ssh -p 2222 localhost agents >> AGENTS.md
  44. ```
  45. Or let your agent do the whole setup:
  46. ```shell
  47. ssh openlore.sh teach | claude
  48. ```
  49. Not on Homebrew? See the [Quickstart](docs/start/quickstart.md#install) for Linux and Windows.
  50. ## Why not just keep Markdown in your repo?
  51. For one agent in one repository, do that.
  52. OpenLore is for when several agents, repositories or people need the same knowledge, and you need to say who can read, write or publish what. Update a file once and every agent sees the new version on its next read.
  53. There's no vector database, ingestion pipeline or SDK. Your knowledge stays as ordinary Markdown.
  54. ## Guides
  55. - [What is OpenLore](docs/introduction.md)
  56. - [Claude Code](docs/start/agents/start-claude-code.md)
  57. - [Codex](/docs/start/agents/codex.md)
  58. - [Cursor](/docs/start/agents/cursor.md)
  59. - [OpenCode](/docs/start/agents/opencode.md)
  60. - [Meta Muse](/docs/start/agents/meta-muse.md)
  61. - [OpenAI dots](/docs/start/agents/openai-dots.md)
  62. - [Grok Bot](/docs/start/agents/grok-bot.md)
  63. - [Claude Duet](/docs/start/agents/claude-duet.md)
  64. - [LangChain](/docs/start/agents/langchain.md)
  65. - [Any agent over SSH](docs/start/agents/start-ssh.md)
  66. - [Let an agent publish into an inbox](docs/how-to/publish-to-inbox.md)
  67. - [Deploy to Render](docs/how-to/deploy/render.md)
  68. - [Prune a knowledge repository from its analytics](docs/recipes/knowledge-cleanup.md)
  69. - [Build an LLM wiki on OpenLore](docs/recipes/llm-wiki.md)
  70. - [Share a coding style guide with every agent](docs/recipes/coding-style-guide.md)
  71. - [All documentation](https://openlore.sh/docs/)
  72. ## Features
  73. - **Agent-native retrieval** — Agents use the shell tools and composition
  74. patterns they already understand instead of learning a bespoke retrieval API.
  75. - **One knowledge surface, multiple transports** — Serve the same virtual
  76. filesystem over SSH, SFTP/SSHFS (including direct VS Code browsing and
  77. editing), MCP, and a human-friendly web view.
  78. - **Live, governed knowledge** — Keep content read-only, allow scoped publishing,
  79. or enable full writes per docset. Writes are atomic, conflict-aware and
  80. validated before they commit.
  81. - **Identity-scoped views** — Give each person or agent only the docsets it
  82. needs, with role-based `ro`, `publish`, and `rw` grants, path aliases, and
  83. private home directories.
  84. - **Safe by construction** — The shell is an in-memory Go interpreter, not a
  85. real operating-system shell. There is no shell escape, arbitrary process
  86. execution, or ambient network access in a normal session.
  87. - **Portable knowledge bundles** — Embed docs into a self-contained binary,
  88. build cross-platform bundles with the GitHub Action, or package them as a
  89. desktop MCP extension.
  90. - **Structured knowledge without a new query language** — Inspect frontmatter
  91. as NDJSON with `lore meta`, query it with `jq`, and validate Google's
  92. [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
  93. bundles and Agent Skills close to the write path.
  94. - **Extensible policy and processing** — Plugins can add validation, grants,
  95. read/write middleware, metadata, and post-commit processing while preserving
  96. the same filesystem interface.
  97. ## Use Cases
  98. - **Continuous Learning repository** - store sessions and learnings in one shared server. Add metrics so you can optimise. Allow agents to share learnings with each other while maintaining user isolation.
  99. - **Team Artifact Repository** - share markdown, HTML, JSON, Excel etc. documents you've created while maintaining access controls. Much more natural than git, more agent-native than Confluence/Notion.
  100. - **Documentation for coding agents** — Put internal API docs, runbooks, product
  101. context, and architecture notes behind a familiar, greppable interface.
  102. - **A shared live memory for teams of agents** — Give agents separate or shared
  103. docsets so they can publish findings, hand off work, and accumulate durable
  104. context across sessions.
  105. - **Public docs site** - add any files to your public docset, enable public access and it will be shown to any agent that stumbles across your site. Improves AEO/GEO with no need to edit your existing docs.
  106. - **Skills sharing** — Publish Agent Skills into shared collections so every
  107. authorised agent can discover and use the same governed procedures.
  108. - **Agent Plugins repository** — Version-pin [Agent Plugins](https://agent-plugins.org) repos from GitHub and serve them to your team's agents. Skills packaged in the open standard stay current automatically.
  109. - **Governed knowledge contribution** — Let contributors publish into inboxes
  110. while reserving existing documents for maintainers and preventing accidental
  111. overwrites.
  112. - **Artifact repository** — Store and expose reports, logs, screenshots, and
  113. generated files through the browser or SSH without building a custom artifact
  114. viewer or granting access to the agent's machine.
  115. - **Identity-specific workspaces** — Mount a private home for each agent plus
  116. shared team knowledge, all through one server and one authorisation model.
  117. - **Portable customer or project knowledge** — Ship a versioned executable with
  118. the relevant docs embedded, or distribute the same knowledge as an MCPB
  119. desktop extension.
  120. - **Validated knowledge catalogues** — Enforce frontmatter and bundle conventions,
  121. inspect metadata cheaply, and stop malformed knowledge at admission time.
  122. ## How It Works
  123. OpenLore is built on [Wish](https://github.com/charmbracelet/wish) for SSH
  124. transport. A connection is handled entirely against a virtual filesystem:
  125. 1. **Authenticate** — connect keylessly or resolve an SSH key, certificate,
  126. passkey, or OAuth login to an identity.
  127. 2. **Compose a view** — mount only the docsets and paths granted to that identity.
  128. 3. **Explore** — run shell commands implemented as pure Go functions over that
  129. view, or use the equivalent MCP `lore_bash` tool.
  130. 4. **Contribute safely** — if writing is enabled, authorise and validate a
  131. whole-file change before committing it atomically.
  132. OAuth clients use delegated identities, so durable write provenance distinguishes
  133. direct work by `adil` from work performed as `adil/claude@claude.ai`. Delegates
  134. can inherit no more authority than their principal and can be narrowed by
  135. docset and capability deny lists. CIMD clients can additionally authenticate
  136. with vendor-hosted metadata and `private_key_jwt`; see
  137. [Authenticated OAuth Clients](docs/reference/authenticated-oauth-clients.md).
  138. The normal shell cannot invoke `bash`, `exec`, `curl`, or arbitrary host
  139. processes. Embedded documentation is always read-only. Explicitly trusted
  140. identities can be granted narrowly scoped asynchronous processing through the
  141. `spawn` capability.
  142. ## Governed Writing
  143. OpenLore is read-only by default. Writable deployments keep a single,
  144. policy-controlled write path for redirects, append, `tee`, `patch`, `sed -i`,
  145. file moves, publishing, and trusted external jobs.
  146. ```shell
  147. echo "# Research" | publish /backend/findings.md
  148. cat change.diff | patch /backend/api.md
  149. sed -i 's/old/new/g' /backend/runbook.md
  150. ```
  151. Writes are whole-object atomic swaps. Compare-and-swap protection rejects stale
  152. edits by default, docset grants constrain the target, and plugins can validate
  153. or defer a write before it commits.
  154. See [Writing and publishing](docs/concepts/writing.md) for user-facing setup and
  155. [Write system internals](docs/reference/write-system.md) for the implementation model.
  156. ## Installation
  157. See the [Quickstart](docs/start/quickstart.md#install) for Homebrew, Linux and
  158. Windows releases, and which installations include the dashboard. To build
  159. OpenLore yourself, see [Building from source](docs/reference/building-from-source.md).
  160. ### Embed docs in a binary
  161. Place documentation in `assets/lore/` and build. The resulting binary contains
  162. the docs and serves them read-only at `/docs` when run with no directory
  163. argument:
  164. ```shell
  165. make dashboard-build # optional: include the web UI
  166. go build -o my-docs ./cmd/openlore
  167. ```
  168. ### Build with the GitHub Action
  169. Produce cross-platform binaries with your docs embedded:
  170. ```yaml
  171. - uses: aakarim/openlore@v1
  172. with:
  173. docs-dir: ./docs
  174. config: ./openlore.yml
  175. ```
  176. See [Ways to use OpenLore](docs/how-to/usage.md) for direct VS Code editing, MCP stdio,
  177. MCPB desktop packaging, SSHFS, and Go library usage.
  178. ### Create a customised deployment
  179. Use the bundled `setup` skill to create `<team>-lore`, a small customer-owned
  180. repository containing `openlore.yml`, a thin `Containerfile` pinned to an
  181. official OpenLore release, and deployment artifacts. It builds a working local
  182. server and verifies HTTP, MCP, authenticated SSH, writes, and persistence before
  183. deployment:
  184. ```shell
  185. ssh openlore.sh setup | amp
  186. ```
  187. The generated repository keeps initial `lore.json` policy and SSH-visible files
  188. under gitignored `.local/`. The first deployment initialises an empty persistent
  189. volume from that state. Root `openlore.yml` remains the Git/IaC authority and is
  190. deployed separately to `/var/lib/openlore/config/openlore.yml`; it is not baked
  191. into the image. Later `lore.json` and filesystem edits on the server are
  192. authoritative and are never overwritten by image updates.
  193. Additional instruction commands support the full lifecycle:
  194. - `onboarding` adds initial identities, roles, homes, and folders locally;
  195. - `deploy` selects Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean, or a
  196. custom deployment and verifies a shared persistence/networking contract;
  197. - `upgrade` prepares only the pinned base-image version change so existing CD
  198. can deploy it.
  199. Provider deployments require HTTPS/MCP, authenticated OpenLore SSH,
  200. administrative shell access, and a persistent `/var/lib/openlore` volume. Where
  201. the provider supports it, deployment configures public port 22 to forward to
  202. OpenLore port 2222. Otherwise it reports the assigned port and recommends an
  203. external TCP forwarding system.
  204. The published container contains only OpenLore. It deliberately contains no
  205. onboarding policy or server configuration. Before the service starts, the
  206. deployment must put `openlore.yml` and `lore.json` in the persistent config
  207. directory and run:
  208. ```shell
  209. ./out --config /var/lib/openlore/config/openlore.yml
  210. ```
  211. This keeps configuration independently deployable: a simple deployment can
  212. copy `openlore.yml` onto the volume, while Kubernetes can project the same file
  213. from a ConfigMap. Use the `deploy` skill for Fly.io, Railway, AWS, Google Cloud,
  214. Azure, DigitalOcean, or custom infrastructure. The repository's Railpack and
  215. Fly files provide the image, persistent-volume, and port wiring; they do not
  216. seed or mutate configuration at process startup.
  217. For a quick hosted server without a customised repository, use the
  218. [Deploy to Render](docs/how-to/deploy/render.md) button. Unlike the Railpack and Fly files,
  219. its start script writes a starter `openlore.yml` and `lore.json` to an empty
  220. disk on first boot. Render serves HTTPS, MCP and the web view only; it has no
  221. public TCP ingress for OpenLore SSH.
  222. Railway assigns its SSH TCP proxy a public hostname and port. Standard SSH port
  223. 22 requires an external raw TCP load balancer. Fly.io can map public port 22 to
  224. OpenLore's internal port 2222 with a dedicated address. Raw SSH has no hostname
  225. or SNI routing, so one listener cannot route multiple domains on port 22.
  226. The container workflow publishes `latest` from `main`; releases also publish
  227. `VERSION`, `vVERSION`, major, and minor image tags.
  228. ## Documentation
  229. The same pages, in the same groups, are published at
  230. [openlore.sh/docs](https://openlore.sh/docs/).
  231. ### Introduction
  232. | Page | Contents |
  233. |---|---|
  234. | [What is OpenLore](docs/introduction.md) | Serve, connect, scope, govern and observe in one page |
  235. | [Changelog](docs/changelog.md) | Current version, release notes, compatibility notes, and versioned docs |
  236. ### Start
  237. | Page | Contents |
  238. |---|---|
  239. | [Quickstart](docs/start/quickstart.md) | Install OpenLore, serve a folder, and connect an agent |
  240. | [Claude Code](docs/start/agents/start-claude-code.md) | Connect Claude Code over MCP and scope what it sees |
  241. | [Codex](docs/start/agents/codex.md) | Connect Codex over MCP |
  242. | [Cursor](docs/start/agents/cursor.md) | Connect Cursor over MCP |
  243. | [OpenCode](docs/start/agents/opencode.md) | Connect OpenCode over MCP |
  244. | [Meta Muse](docs/start/agents/meta-muse.md) | Connect Meta Muse over MCP |
  245. | [OpenAI dots](docs/start/agents/openai-dots.md) | Connect OpenAI dots over MCP |
  246. | [Grok Bot](docs/start/agents/grok-bot.md) | Connect Grok Bot over MCP |
  247. | [Claude Duet](docs/start/agents/claude-duet.md) | Connect Claude Duet over MCP |
  248. | [LangChain](docs/start/agents/langchain.md) | Connect a LangChain agent over MCP and give it an identity |
  249. | [Any agent over SSH](docs/start/agents/start-ssh.md) | Connect a coding agent or CI job over SSH and give it an identity |
  250. ### Concepts
  251. How OpenLore works: docsets, transports, identity, writes, rules, and observation.
  252. | Page | Contents |
  253. |---|---|
  254. | [Docsets](docs/concepts/docsets.md) | What a docset is, why access is organised around them, and how nesting, grants, aliases and fail-closed validation work |
  255. | [Transports](docs/concepts/transports.md) | How SSH, SFTP, MCP, the JSON API and the web share one filesystem, the MCP tools, command results, sessions, and instruction commands |
  256. | [Auth](docs/concepts/auth.md) | Authentication posture, how SSH keys, certificates, passkeys, OAuth tokens and inbox credentials resolve to an identity, roles, docsets, aliases, homes, and workload identity federation |
  257. | [Writing and publishing](docs/concepts/writing.md) | Write modes, inboxes, conflict handling, what a successful write does and does not check, and jobs |
  258. | [Folder rules](docs/concepts/folder-rules.md) | `.lore/config.yaml` and `lore.json` rules, layering, permissions, rejection messages, and growth limits |
  259. | [Plugins and formats](docs/concepts/plugins.md) | Provider interfaces, Open Knowledge Format validation, `lore validate`, `lore meta`, and the Agent Skills plugin |
  260. | [Dashboard and metrics](docs/concepts/dashboard.md) | Dashboard authentication, facts versus activity, and the file viewer |
  261. ### How to
  262. Task walkthroughs.
  263. | Page | Contents |
  264. |---|---|
  265. | [Ways to use OpenLore](docs/how-to/usage.md) | Set up SSH, MCP over HTTP and stdio, the web view, SSHFS, embedded binaries, the GitHub Action, MCPB, and library usage |
  266. | [Configure the server](docs/how-to/configure-the-server.md) | Create `openlore.yml`, precedence over embedded config and flags, HTTPS, analytics, and debug logging |
  267. | [Production checklist](docs/how-to/production-checklist.md) | What a shared server needs before cloud agents can reach it: a host with HTTPS out of the box, a pinned image on a volume, a public origin, a token on `/mcp`, passkeys |
  268. | [Let an agent publish into an inbox](docs/how-to/publish-to-inbox.md) | Accept contributions from an agent without letting it edit anything else |
  269. | [Browse and edit from an editor](docs/how-to/editors.md) | Direct VS Code and SFTP editor setup without a local project mirror |
  270. | [Run headlong / shellm](docs/how-to/shellm.md) | Use OpenLore over SSH from headlong's shellm engine, including its housekeeping skill |
  271. | [Build from source](docs/reference/building-from-source.md) | Build the web UI and binary yourself, or build without the web UI |
  272. | [Deploy OpenLore to Render](docs/how-to/deploy/render.md) | One-click Render deployment, first passkey sign-in, upgrades, and custom domains |
  273. ### Reference
  274. Lookup material: commands, keys, endpoints, interfaces, and internals.
  275. | Page | Contents |
  276. |---|---|
  277. | [Command reference](docs/reference/commands.md) | Complete shell, introspection, publishing, syntax, CLI command, and flag reference |
  278. | [openlore.yml reference](docs/reference/openlore-yml.md) | Generated reference for every key `openlore.yml` accepts |
  279. | [Rules standard library](docs/reference/rules-stdlib.md) | Generated reference for compiled-in rule members and their parameters |
  280. | [HTTP inbox API](docs/reference/inbox.md) | `POST /inbox/{docset}` with bearer or HMAC credentials, and the token endpoints |
  281. | [OAuth clients](docs/reference/authenticated-oauth-clients.md) | CIMD client identity, `private_key_jwt`, mTLS corroboration, and signing-key rotation |
  282. | [Write system internals](docs/reference/write-system.md) | Filesystem layering, write seam, admission middleware, and async jobs |
  283. | [Build the dashboard](docs/reference/dashboard-build.md) | Frontend build and backend-only Go builds |
  284. | [Security evaluation](SECURITY.md) | Threat model and security properties |
  285. ## Security
  286. - Commands run in a pure-Go interpreter, not through `os/exec`.
  287. - The virtual filesystem cleans paths and enforces docset boundaries.
  288. - Allowed file patterns and ignored directories keep secrets out of the view.
  289. - RBAC controls reads, publishing, writes, approvals, and trusted capabilities.
  290. - The web endpoint can publish the SSH host key over TLS to avoid blind trust on
  291. first use; SSH user and host certificates are also supported.
  292. See [SECURITY.md](SECURITY.md) for the full security evaluation.
  293. ## License
  294. [Apache License 2.0](LICENSE) — Copyright © 2026 Adil Karim
  295. OpenLore bundles third-party open-source components. Their licences and required
  296. notices are listed in
  297. [assets/legal/THIRD_PARTY_NOTICES.md](assets/legal/THIRD_PARTY_NOTICES.md), with
  298. full licence texts in [assets/legal/licenses/](assets/legal/licenses/). These are
  299. embedded in the binary and served by the running service at `/legal`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.