📜 OpenLore

📜 OpenLore

Sponsored by

Serve your docs to AI agents over SSH.

OpenLore is a minimal, extensible, agent-native knowledge base that keeps shared context current and inspectable.

About

AI coding agents already know how to explore files with ls, cat, grep,find, pipes, and shell loops. OpenLore gives them that same interface overSSH, backed by your documentation instead of a real machine.

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

It starts as a single-binary, zero-config, read-only documentation server. Whenyou need a live knowledge base, you can add identity-scoped access, controlledpublishing, atomic writes, validation, and human approval without changing howagents read or navigate the content.

Store and retrieve Markdown

Put documentation, runbooks, project context, or agent-authored notes inordinary Markdown files. There is no ingestion pipeline: point OpenLore at adirectory and it serves the existing hierarchy directly. Organize documentswith folders, connect them with standard Markdown links, and group them intodocsets when different people or agents need different access. OpenLore isread-only by default; enable writing when you want agents to create and updateMarkdown too.

Quick Start

The fastest path is to let your agent set up 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

Or install and run it directly:

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

openlore ./docs

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

By default this starts:

• SSH on localhost:2222
• the human-facing web view on http://localhost:8080
• MCP over HTTP on http://localhost:8080/mcp

See Installation for more ways to install and package OpenLore.

Features

• Agent-native retrieval — Agents use the shell tools and compositionpatterns they already understand instead of learning a bespoke retrieval API.
• One knowledge surface, multiple transports — Serve the same virtualfilesystem over SSH, SFTP/SSHFS, MCP, and a human-friendly web view.
• Live, governed knowledge — Keep content read-only, allow scoped publishing,or enable full writes per docset. Writes are atomic, conflict-aware, and canrequire human approval.
• Identity-scoped views — Give each person or agent only the docsets itneeds, with role-based ro, publish, and rw grants, path aliases, andprivate home directories.
• Safe by construction — The shell is an in-memory Go interpreter, not areal operating-system shell. There is no shell escape, arbitrary processexecution, or ambient network access in a normal session.
• Portable knowledge bundles — Embed docs into a self-contained binary,build cross-platform bundles with the GitHub Action, or package them as adesktop MCP extension.
• Structured knowledge without a new query language — Inspect frontmatteras NDJSON with lore meta, query it with jq, and validate Google'sOpen Knowledge Format (OKF)bundles and Agent Skills close to the write path.
• Extensible policy and processing — Plugins can add validation, grants,read/write middleware, metadata, and post-commit processing while preservingthe same filesystem interface.

Use Cases

• 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.
• 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.
• Documentation for coding agents — Put internal API docs, runbooks, productcontext, and architecture notes behind a familiar, greppable interface.
• A shared live memory for teams of agents — Give agents separate or shareddocsets so they can publish findings, hand off work, and accumulate durablecontext across sessions.
• 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.
• Skills sharing — Publish Agent Skills into shared collections so everyauthorized agent can discover and use the same governed procedures.
• Agent Plugins repository — Version-pin Agent Plugins repos from GitHub and serve them to your team's agents. Skills packaged in the open standard stay current automatically.
• Governed knowledge contribution — Let contributors publish into inboxeswhile reserving sensitive paths for approvers and preventing accidentaloverwrites.
• Remote review of agent artifacts — Expose reports, logs, screenshots, andgenerated files through the browser or SSH without building a custom artifactviewer or granting access to the agent's machine.
• Identity-specific workspaces — Mount a private home for each agent plusshared team knowledge, all through one server and one authorization model.
• Portable customer or project knowledge — Ship a versioned executable withthe relevant docs embedded, or distribute the same knowledge as an MCPBdesktop extension.
• Validated knowledge catalogs — Enforce frontmatter and bundle conventions,inspect metadata cheaply, and stop malformed knowledge at admission time.

How It Works

OpenLore is built on Wish for SSHtransport. A connection is handled entirely against a virtual filesystem:

1. Authenticate — connect keylessly or resolve an SSH key, certificate,passkey, or OAuth login to an identity.
2. Compose a view — mount only the docsets and paths granted to that identity.
3. Explore — run shell commands implemented as pure Go functions over thatview, or use the equivalent MCP shell tool.
4. Contribute safely — if writing is enabled, authorize and validate awhole-file change before committing it atomically or routing it for approval.

OAuth clients use delegated identities, so durable write provenance distinguishesdirect work by adil from work performed as adil/[email protected]. Delegatescan inherit no more authority than their principal and can be narrowed bydocset and capability deny lists. CIMD clients can additionally authenticatewith vendor-hosted metadata and private_key_jwt; seeAuthenticated OAuth Clients.

The normal shell cannot invoke bash, exec, curl, or arbitrary hostprocesses. Embedded documentation is always read-only. Explicitly trustedidentities can be granted narrowly scoped asynchronous processing through thespawn capability.

Governed Writing

OpenLore is read-only by default. Writable deployments keep a single,policy-controlled write path for redirects, append, tee, patch, sed -i,file moves, publishing, and approved external jobs.

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

Writes are whole-object atomic swaps. Compare-and-swap protection rejects staleedits by default, docset grants constrain the target, and selected paths canproduce reviewable changesets under /requests instead of committing directly.

See Writing and publishing for user-facing setup andWrite system internals for the implementation model.

Installation

Install with Go

Requires Go 1.26 or later:

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

Build from source

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

Embed docs in a binary

Place documentation in assets/lore/ and build. The resulting binary containsthe docs and serves them read-only at /docs when run with no directoryargument:

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

Build with the GitHub Action

Produce cross-platform binaries with your docs embedded:

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

See Ways to use OpenLore for MCP stdio, MCPB desktoppackaging, SSHFS, and Go library usage.

HTTP inbox uploads

Configure a docset inbox and a role with its publish grant, then create acredential for an existing identity (the server configuration must nameauth_file so the CLI can validate it):

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} accepts bearer credentials or an exact-body HMAC usingX-OpenLore-Token-Id and X-OpenLore-Signature. OAuth access tokens are usedonly for POST/GET /inbox/tokens and DELETE /inbox/tokens/{id}; inboxcredentials are separate and revocable. SeeConfiguration and identity.

Documentation

Security

• Commands run in a pure-Go interpreter, not through os/exec.
• The virtual filesystem cleans paths and enforces docset boundaries.
• Allowed file patterns and ignored directories keep secrets out of the view.
• RBAC controls reads, publishing, writes, approvals, and trusted capabilities.
• The web endpoint can publish the SSH host key over TLS to avoid blind trust onfirst use; SSH user and host certificates are also supported.

See SECURITY.md for the full security evaluation.

License

MIT — Adil Karim

OpenLore bundles third-party open-source components. Their licenses and requirednotices are listed inassets/legal/THIRD_PARTY_NOTICES.md, withfull license texts in assets/legal/licenses/. These areembedded in the binary and served by the running service at /legal.