### List and fetch guides from server
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/teach.md
Fetch guides as needed from the server. Replace
with the server address. The first command lists every guide the server carries; the second fetches one by name (e.g., passkeys, upgrade, deploy-fly).
```shell
ssh skills # list every guide the server carries
ssh # fetch one, e.g. passkeys, upgrade, deploy-fly
```
--------------------------------
### Fetch onboarding and deploy skills after setup
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/teach.md
After the setup skill completes, fetch the onboarding skill to add identities and the deploy skill to share the server with the team.
```shell
ssh openlore.sh onboarding
ssh openlore.sh deploy
```
--------------------------------
### Fetch setup skill for new Lore server
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/teach.md
Fetch and follow the setup skill when creating a new Lore server (option A). It collects team name and location, installs the official lore client if needed, and runs lore init to create the repository.
```shell
ssh openlore.sh setup
```
--------------------------------
### Install OpenLore via Homebrew
Source: https://github.com/aakarim/openlore/blob/main/docs/start/quickstart.md
Installs both the `openlore` server and `lore` client binaries together on macOS and Linux.
```shell
brew install --cask aakarim/tap/lore
```
--------------------------------
### Install OpenLore Linux release
Source: https://github.com/aakarim/openlore/blob/main/docs/start/quickstart.md
Downloads and installs the latest x86-64 Linux release. Arm64 archives are published as `openlore_linux_arm64.tar.gz`.
```shell
curl -L https://github.com/aakarim/OpenLore/releases/latest/download/openlore_linux_amd64.tar.gz | tar xz
sudo install openlore lore /usr/local/bin
```
--------------------------------
### Install OpenLore Windows release
Source: https://github.com/aakarim/openlore/blob/main/docs/start/quickstart.md
Downloads and extracts the latest 64-bit Windows release from PowerShell. The archive contains `lore.exe`; keep both on your `PATH`.
```powershell
Invoke-WebRequest `
-Uri https://github.com/aakarim/OpenLore/releases/latest/download/openlore_windows_amd64.zip `
-OutFile openlore.zip
Expand-Archive openlore.zip -DestinationPath .
.\openlore.exe version
```
--------------------------------
### Let an agent perform the whole setup with ssh openlore.sh teach
Source: https://github.com/aakarim/openlore/blob/main/README.md
Pipes the output of `ssh openlore.sh teach` into the `claude` CLI, letting the agent handle the entire setup automatically.
```shell
ssh openlore.sh teach | claude
```
--------------------------------
### Fetch server instructions for agent onboarding
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/teach.md
Fetch the server's own instructions for onboarding agents. Replace {{ ssh_target }} with the server address. The first command retrieves a portable Agent Skills file, the second an AGENTS.md snippet.
```shell
ssh {{ ssh_target }} openlore-skill # portable Agent Skills file
ssh {{ ssh_target }} agents # AGENTS.md snippet
```
--------------------------------
### Open setup record (macOS/Linux)
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/onboarding.md
Open the setup record file in the default editor. Use the macOS command on macOS and the Linux command on Linux; if neither opener exists, provide the absolute path instead.
```bash
open content/channel/infrastructure/openlore-server.md # macOS
```
```bash
xdg-open content/channel/infrastructure/openlore-server.md # Linux
```
--------------------------------
### Serve docs with openlore
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/getting-started.md
Starts the OpenLore server, serving documentation to AI agents over SSH. The main server also exposes an MCP-over-HTTP endpoint on by default at /mcp on the same port and TLS.
```shell
openlore ./docs
```
--------------------------------
### Install and initialize a knowledge repository with brew and lore init
Source: https://github.com/aakarim/openlore/blob/main/README.md
Installs the `lore` CLI via Homebrew and creates a new knowledge repository named `my-knowledge`. `lore init` creates the folder and an `openlore.yml` with default server settings. If already in a knowledge repository, run `lore init` without a directory.
```shell
brew install --cask aakarim/tap/lore
lore init my-knowledge
cd my-knowledge
```
--------------------------------
### Startup banner: no passkey registered
Source: https://github.com/aakarim/openlore/blob/main/docs/concepts/dashboard.md
Multi-line guide shown when no passkey is registered. Lists steps: register via SSH, open link in browser, and sign in at the dashboard.
```text
Dashboard: no passkey is registered yet
next steps:
1. from any SSH shell, run `ssh -p 2222 localhost passkey register --identity adil` (any identity in lore.json, with or without an SSH key)
2. within 5 minutes, open the printed link in a browser on the device whose passkey you want to use; the link must be opened at an origin listed in `passkeys.rp_origins` (currently http://localhost:8080)
3. open http://localhost:8080/dashboard/ and sign in with that passkey; the session lasts `passkeys.session_ttl`
```
--------------------------------
### Prompt for agent to write Go style guide into OpenLore
Source: https://github.com/aakarim/openlore/blob/main/docs/recipes/coding-style-guide.md
Use this prompt with a coding agent inside the repository to generate a style guide. The agent fetches Google's guide with its own web tool because the server shell has no network, and writes files via the openlore MCP shell or ssh. Replace 'go' with your language and the Google URLs with the matching guide. The prompt includes size limits (guide under 300 lines, decisions pages under 2,000 tokens) and requires running 'lore validate /style' before finishing.
```text
Write our team's Go style guide into the OpenLore knowledge repository. Use
the openlore MCP shell for every command on the server (or
`ssh -p 2222 ''`); the server shell has no network, so
fetch web pages with your own tools.
1. Read the Google Go Style Guide at
https://google.github.io/styleguide/go/guide and skim the Style Decisions
at https://google.github.io/styleguide/go/decisions. Keep the guide's
structure: style principles first, then core guidelines.
2. Read this repository's go.mod, linter configuration, Makefile, any
existing AGENTS.md or CONTRIBUTING.md, and a sample of the packages under
internal/ and pkg/. Note where our code already differs from Google's
guidance (for example error wrapping, logging, test layout, package
naming) and treat the existing convention as ours unless it is
contradicted by a linter we run.
3. Write /style/go/guide.md with tee. It must be under 300 lines; the
server rejects a longer file. It is the file every agent reads in full
before writing Go here, so every line must be a rule or a principle,
with at most one short example per rule. Drop anything specific to
Google's internal process or libraries. Add the rules from step 2 under
their own heading, "Local conventions". Where a rule has reasoning
longer than a sentence, state the rule and link to a decisions page:
`See [decisions/errors.md](decisions/errors.md)`.
4. Write one page per topic under /style/go/decisions/, following the
sections of Google's Style Decisions (naming, commentary, imports,
errors, language, testing, and whatever local topics step 2 produced).
Each page must stay under 2,000 tokens, which is about 8,000 bytes; the
server rejects a larger page. Open each page with the rule in one
sentence, then the reasoning and the examples. Cite the Google section
the page is adapted from.
5. Write /style/index.md: one paragraph on how to use the docset (read
guide.md in full, read one decisions page when a question comes up),
then a list of every file with a one-line description.
6. Check the budgets before you finish:
`wc -l /style/go/guide.md` and
`wc -c /style/go/decisions/*.md`. Then run `lore validate /style`. If a
write is rejected by a size rule, follow its `suggested:` line and move
material into a linked page; do not retry with small trims.
7. Reply with the path of every file you wrote, the line count of
guide.md, and the byte count of the largest decisions page.
Write only inside /style/go and /style/index.md.
```
--------------------------------
### Explore documentation on existing Lore server
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/teach.md
Commands to explore the server's documentation after connecting. Lists all docs, mounts and access levels, searches across docs, reads a file, and shows the full command list.
```shell
tree -L 2 / # list all documentation
lore docsets # mounts and access levels
grep -r "term" / # search across docs
cat # read a file
help # full command list
```
--------------------------------
### Open the completed setup record
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/deploy.md
Provides three ways to open the completed setup record depending on whether a passkey is registered and whether the local content was kept. The first command opens the rendered page on the server (use xdg-open on Linux), the second opens the local copy if content was kept, and the third reads it via SSH.
```bash
open "https:///lore/channel/infrastructure/openlore-server.md" # passkey registered (xdg-open on Linux)
```
```bash
open content/channel/infrastructure/openlore-server.md # no passkey, content kept
```
```bash
ssh 'cat /channel/infrastructure/openlore-server.md' # otherwise
```
--------------------------------
### Serve docs with MCP endpoint
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/getting-started.md
Starts the OpenLore server with the MCP-over-HTTP endpoint enabled by default at /mcp on the HTTP server (sharing the same port and TLS). The output shows the MCP endpoint URL.
```shell
openlore ./docs
# MCP: http://localhost:8080/mcp
```
--------------------------------
### Example question for the agent
Source: https://github.com/aakarim/openlore/blob/main/docs/start/agents/langchain.md
Example question to pass as the script argument. The agent searches with grep -r through the shell tool and answers from the result.
```prompt
What does the knowledge repository say about our retry policy?
```
--------------------------------
### Install without web UI using go install
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/building-from-source.md
Installs the latest version of the OpenLore binary without the web UI. This does not require Node and skips the dashboard. SSH, MCP, the JSON API, and published file links still work; only the dashboard is missing.
```shell
go install github.com/aakarim/go-openlore/cmd/openlore@latest
```
--------------------------------
### Agent commands in restricted interpreter
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/getting-started.md
Example commands agents can run in OpenLore's restricted interpreter (not Bash) to list, search, read, find, and process documentation.
```shell
# List all documentation
tree -L 2 /
# Search across all docs
grep -r "authentication" /docs
# Read specific files
cat /docs/api-reference.md
# Find files by name
find / -name "*.md"
# Process JSON
cat /docs/config.json | jq '.settings'
```
--------------------------------
### Create docset folders
Source: https://github.com/aakarim/openlore/blob/main/docs/start/create-knowledge-repository.md
Creates the directories that the docsets point at before starting the server.
```shell
mkdir -p content/notes content/user/alice
```
--------------------------------
### Create a customised deployment with ssh openlore.sh setup | amp
Source: https://github.com/aakarim/openlore/blob/main/README.md
Use the bundled setup skill to create -lore, a small customer-owned repository containing openlore.yml, a thin Containerfile pinned to an official OpenLore release, and deployment artifacts. It builds a working local server and verifies HTTP, MCP, authenticated SSH, writes, and persistence before deployment.
```shell
ssh openlore.sh setup | amp
```
--------------------------------
### lore agent import
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/lore-cli.md
Runs the guided Claude Code setup, identical to `lore source add claude` and accepting the same flags. With no profile, it lists the available profiles.
```APIDOC
## lore agent import
### Description
Runs the guided Claude Code setup, identical to `lore source add claude` and accepting the same flags. With no profile, it lists the available profiles.
### Usage
`lore agent import [claude] [path] [--project] [--personal]`
### Parameters
- **claude** (string) - Optional - The profile to import.
- **path** (string) - Optional - The directory to run Claude Code in.
- **--project** (flag) - Optional - Limit to project scope.
- **--personal** (flag) - Optional - Limit to personal scope.
### Request Example
```shell
lore agent import claude --project
```
```
--------------------------------
### Discover installed skills with the skills metadata filter
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/commands.md
Use the `skills` metadata filter to find installed skills, then read the chosen `SKILL.md`. The example filters for skills whose name or description matches "pdf" (case-insensitive) and prints the path.
```shell
lore meta --filter skills | jq -r 'select((.name + " " + .description) | test("pdf"; "i")) | .path'
```
--------------------------------
### Measure guide size with wc
Source: https://github.com/aakarim/openlore/blob/main/docs/recipes/coding-style-guide.md
Shell commands to measure the guide's lines and bytes and list the five largest decisions pages. The first line gives the guide's lines and bytes; the second lists the five largest pages. Tokens are bytes divided by four under estimate/v1.
```shell
wc -l -c /style/go/guide.md
wc -c /style/go/decisions/*.md | grep -v total | sort -rn | head -5
```
--------------------------------
### Install SSH host key and connect
Source: https://github.com/aakarim/openlore/blob/main/docs/concepts/auth.md
Fetches the OpenLore public host key over HTTPS and appends it to ~/.ssh/known_hosts for the docs.example.com host on port 2222, then connects via SSH. Use after placing the HTTP server behind TLS to avoid trust-on-first-use warnings.
```shell
curl -s https://docs.example.com/host-key | \
awk '{print "[docs.example.com]:2222 " $0}' >> ~/.ssh/known_hosts
ssh -p 2222 docs.example.com
```
--------------------------------
### Initialize knowledge repository with lore init
Source: https://github.com/aakarim/openlore/blob/main/docs/start/quickstart.md
Creates a folder for your team's knowledge and an `openlore.yml` with default server settings. To initialize the current folder, run `lore init` without a directory. It never overwrites an existing `openlore.yml`.
```shell
lore init my-knowledge
cd my-knowledge
```
--------------------------------
### Package as desktop extension (.mcpb) with go build and openlore mcpb
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/mcp.md
Package the binary (with embedded docs) as an MCPB extension for one-click installation in Claude Desktop. Build with 'go build -o openlore ./cmd/openlore' then run './openlore mcpb -o openlore.mcpb'. If the binary has no embedded docs, the user is prompted to select a docs directory on install; add '--docs-dir ./docs' to bundle a directory.
```shell
go build -o openlore ./cmd/openlore
./openlore mcpb -o openlore.mcpb
```
--------------------------------
### Verify style guide via SSH and lore validate
Source: https://github.com/aakarim/openlore/blob/main/docs/recipes/coding-style-guide.md
Connects as an agent would and reads the guide the way AGENTS.md says to. Expects a line count under 300, one file per topic, and `0 errors, 0 warnings` from `lore validate`, which exits 0 when every page is within budget.
```shell
ssh -p 2222 -i ~/.ssh/coding-agent "wc -l /style/go/guide.md; ls /style/go/decisions; lore validate /style"
```
--------------------------------
### Start server with openlore
Source: https://github.com/aakarim/openlore/blob/main/docs/start/create-knowledge-repository.md
Serves the content directory. Expect the startup banner with config: loaded ./openlore.yml, SSH on port 2222 and HTTP on port 8080. The server reads lore.json from the repository and mounts /notes and /user/alice.
```shell
openlore ./content
```
--------------------------------
### AGENTS.md section for pointing agents to the Go style guide
Source: https://github.com/aakarim/openlore/blob/main/docs/recipes/coding-style-guide.md
Add this section to AGENTS.md (or CLAUDE.md for Claude Code) in every repository the guide covers. It tells the agent to read the full guide via SSH and to read only linked decision pages, never the whole folder. For MCP agents, change the command to `cat /style/go/guide.md` and note it runs in the openlore `lore_bash` tool.
```markdown
## Coding style
The team's Go style guide lives in the OpenLore knowledge repository.
Before writing or reviewing Go, read the guide in full:
ssh -p 2222 cat /style/go/guide.md
It is under 300 lines, so always read all of it. The reasoning behind each
rule is in /style/go/decisions/, one page per topic. When a rule needs
explaining or the guide links to a page, read that page and only that page;
never cat the whole folder. If the guide and the code you are editing
disagree, follow the guide and say so in your reply.
```
--------------------------------
### Journal output example
Source: https://github.com/aakarim/openlore/blob/main/docs/recipes/company-brain.md
Example output from the journal read command, showing one line per write with action, attribution, target, and time.
```json
{"action":"write","attribution":"crm-sync","target":"/sources/support/inbox/2026-10-15T115806-63622ca2bd7628d7-ticket-4821.md","time":"2026-10-15T11:58:06Z"}
{"action":"write","attribution":"research-agent","target":"/teams/platform/inbox/retry-storms.md","time":"2026-10-15T11:57:47Z"}
{"action":"write","attribution":"crm-sync","target":"/sources/crm/accounts.md","time":"2026-10-15T11:57:22Z"}
```
--------------------------------
### Manual build steps for web UI and Go binary
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/building-from-source.md
These are the two steps that `make distribution` runs. The npm commands install dependencies and build the dashboard into `assets/dashboard/dist`; the Go build embeds that directory. Node is only needed for the web UI build, not at runtime.
```shell
npm --prefix dashboard ci
npm --prefix dashboard run build # writes assets/dashboard/dist
go build -trimpath -o openlore ./cmd/openlore
```
--------------------------------
### Startup banner: no authentication configured
Source: https://github.com/aakarim/openlore/blob/main/docs/concepts/dashboard.md
Shown when no auth_file is set. Indicates dashboard data needs identities and suggests setting auth_file in openlore.yml.
```text
Dashboard: no authentication is configured; dashboard data needs identities to sign in as
next step: set `auth_file: ./lore.json` in openlore.yml and restart (see docs/configuration-and-identity.md)
```
--------------------------------
### Allow OpenLore tools in Claude Code settings
Source: https://github.com/aakarim/openlore/blob/main/docs/start/quickstart.md
Adds the OpenLore MCP server to the allowed tools in `~/.claude/settings.json` or the project's `.claude/settings.json`. This prevents Claude Code from prompting or blocking the server's tool calls.
```json
{
"permissions": {
"allow": ["mcp__openlore"]
}
}
```
--------------------------------
### Start OpenLore with HTTP server enabled
Source: https://github.com/aakarim/openlore/blob/main/examples/caddy-reverse-proxy/README.md
Starts OpenLore with the HTTP server enabled on port 8080, serving the documentation in ./docs.
```shell
openlore --http-port 8080 ./docs
```
--------------------------------
### Install Caddy with SSH module using xcaddy
Source: https://github.com/aakarim/openlore/blob/main/examples/caddy-multi-port/README.md
Builds a custom Caddy binary with the SSH module. Requires Go and xcaddy installed.
```shell
xcaddy build --with github.com/mohammed90/caddy-ssh
```
--------------------------------
### Search skill names and descriptions with jq
Source: https://github.com/aakarim/openlore/blob/main/docs/concepts/plugins.md
Search the names and descriptions of skills to find a skill for a task. This example filters for 'pdf' case-insensitively and outputs the skill's path.
```shell
lore meta --filter skills | jq -r 'select((.name + " " + .description) | test("pdf"; "i")) | .path'
```
--------------------------------
### Run the embedded docs server
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/embedding.md
Run the built binary to start the SSH server that serves the embedded documentation.
```shell
./my-docs-server
# SSH server starts, serving embedded docs
```
--------------------------------
### Example lore size baseline output
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/commands.md
Example output from 'lore size baseline' showing the history entries and current cap. The output includes the rule path, growth factor, and per-entry details (timestamp, action, principal, lines, size, tokens).
```text
/docs/backend/decisions/adr-001.md (size/lines via adr-length @ /docs/backend/.lore/config.yaml, growth 1.1)
2026-08-30T09:12:04Z create agent:claude@acme.com 412 lines 12 KiB 3900 tokens (estimate/v1)
2026-09-02T14:01:37Z reset adil 812 lines 21 KiB 6400 tokens (estimate/v1) "ADR grew after review"
current cap: 893 lines
```
--------------------------------
### SSH commands using $HOME and ~
Source: https://github.com/aakarim/openlore/blob/main/docs/concepts/auth.md
Example shell commands that use the identity's home directory via $HOME and ~. The home docset's display path becomes $HOME, enabling ~, ~/path, and cd with no arguments.
```shell
ssh -p 2222 server 'echo $HOME'
ssh -p 2222 server 'cat ~/notes.md'
ssh -p 2222 server 'cd && pwd'
```
--------------------------------
### Run server and show endpoints
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/usage.md
Starts the HTTP server with the given docs directory. The output shows the SSH, Web, and MCP endpoints. MCP over HTTP shares the HTTP server and its TLS or reverse proxy configuration.
```shell
openlore ./docs
# SSH: ssh -p 2222 localhost
# Web: http://localhost:8080
# MCP: http://localhost:8080/mcp
```
--------------------------------
### openlore-server.md - Infrastructure record
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/setup.md
The living record of the server setup, updated by `setup`, `onboarding`, and `deploy`. Contains frontmatter with `type: Infrastructure`, tables for people/agents, server details, identities/access, deployment status, verification, and a link to `log.md`.
```markdown
---
type: Infrastructure
title: Lore server
description: How this OpenLore server was set up, who set it up, and where it runs.
tags: [OpenLore, infrastructure, setup]
author: human:onboarding
generated: { by: /, at: }
status: draft
---
# Summary
# People and agents
| Role | Identity | Details |
| ----- | ------------ | -------------------------------------------------------------- |
| Owner | onboarding | ; ssh- key |
| Agent | | ; delegate of `onboarding` |
# Server
| Item | Value |
| ---------------- | ------------------------------------------------------- |
| Project | `-lore` at `` |
| OpenLore release | `ghcr.io/aakarim/openlore:` |
| Configuration | root `openlore.yml` (Git/IaC authority) |
| Local runtime | |
| Local ports | SSH ``, HTTP `` |
| Set up on | |
# Identities and access
| Identity | Roles | Home | Docsets and grants |
| ------------ | ---------------------- | ------------------ | ------------------------------------------- |
| onboarding | administrator, user | `/user/onboarding` | `general` rw, `infrastructure` rw |
| | agent | — | `general` rw, `infrastructure` rw; delegate of `onboarding` without `lore:config:edit` |
# Deployment
Not deployed yet. The server runs only on for
local verification; `deploy` fills in this section.
# Verification
# History
See [log.md](log.md) for every change to this record.
```
--------------------------------
### Create a full OpenLore server with NewServer
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/usage.md
Starts an OpenLore server serving files from ./docs on ports 2222 (MCP) and 8080 (HTTP), allowing only *.md and *.txt files. Use this to run both MCP and HTTP transports together.
```go
package main
import (
"log"
openlore "github.com/aakarim/go-openlore/pkg/openlore"
)
func main() {
srv, err := openlore.NewServer("./docs",
openlore.WithPort(2222),
openlore.WithHTTPPort(8080),
openlore.WithAllowedPatterns([]string{"*.md", "*.txt"}),
)
if err != nil {
log.Fatal(err)
}
if err := srv.ListenAndServe(); err != nil {
log.Fatal(err)
}
}
```
--------------------------------
### Run OpenLore and Caddy for HTTPS
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/configure-the-server.md
Starts OpenLore on port 8080 and runs Caddy with the given config. OpenLore builds links, OAuth issuer, and passkey origin from its configuration, not the incoming request.
```shell
openlore --http-port 8080 ./docs
caddy run --config Caddyfile
```
--------------------------------
### Verify synced instructions over SSH
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/import-claude-memory.md
Read the synced instructions from your home over SSH. Set `OPENLORE_SERVER` to your server's hostname first, for example `lore.example.com`, or `localhost` for a local server.
```shell
ssh -p 2222 "$OPENLORE_SERVER" "cat ~/claude/CLAUDE.md"
```
--------------------------------
### lore.json configuration with roles, rules, docsets, and identities
Source: https://github.com/aakarim/openlore/blob/main/docs/concepts/auth.md
Complete example of a lore.json file showing top-level keys: allow_keyless, unknown_identity, default_cwd, roles, rules, docsets, and identities. Demonstrates docset access grants (ro, publish, rw), folder rules, and identity home assignment. Note that any matching docset deny wins and capability allows form a union across roles.
```json
{
"allow_keyless": true,
"unknown_identity": "allow",
"default_cwd": "/docs",
"roles": {
"backend": {
"allow": { "capabilities": ["spawn"] }
}
},
"rules": {
"doc-size": { "match": ["**/*.md"], "use": "size/kilobytes", "with": { "max": 60 }, "default": true }
},
"docsets": {
"public": {
"paths": ["/docs/public"],
"access": { "allow": { "guest": "ro", "backend": "ro" } }
},
"backend": {
"paths": ["/docs/api", { "internal/specs": "/docs/specs" }],
"aliases": ["/api"],
"access": { "allow": { "backend": "rw" } },
"rules": {
"format": { "match": ["**/*.md"], "use": "okf" }
},
"config": { "edit": ["backend"] }
},
"backend-home": {
"paths": ["/home/backend"]
}
},
"identities": [
{
"name": "backend-agent",
"public_key": "ssh-ed25519 AAAA...",
"roles": ["backend"],
"home": "backend-home"
}
]
}
```
--------------------------------
### Create a role and add an identity
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/admin.md
Example of creating a role and putting an identity in it. Read the config (which also arms compare-and-swap), produce the updated JSON, write it, then reload.
```shell
cat /opt/openlore/lore.json # read (also arms compare-and-swap)
# … produce the updated JSON with the new role + membership …
echo "$NEW_CONFIG" | write /opt/openlore/lore.json
lore config reload
```
--------------------------------
### Publish a document via prompt
Source: https://github.com/aakarim/openlore/blob/main/docs/start/agents/langchain.md
Example prompt asking the agent to summarize the retry policy and publish it as /handbook/retry-summary.md. The agent pipes the summary into the publish command, and the server routes it to /handbook/inbox/retry-summary.md.
```prompt
Summarise what the knowledge repository says about our retry policy and publish the summary as /handbook/retry-summary.md.
```
--------------------------------
### Run OpenLore with config from persistent volume
Source: https://github.com/aakarim/openlore/blob/main/README.md
Before the service starts, the deployment must put openlore.yml and lore.json in the persistent config directory and run this command. This keeps configuration independently deployable.
```shell
./out --config /var/lib/openlore/config/openlore.yml
```
--------------------------------
### Verify the projected directory with ssh
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/import-git-repository.md
Lists the projected directory through the server. Set OPENLORE_SERVER to your server's hostname first, for example lore.example.com, or localhost for a local server. The listing matches docs/adr/ on the main branch of the repository.
```shell
ssh -p 2222 "$OPENLORE_SERVER" "ls /payments-docs/adr"
```
```text
0001-record-architecture-decisions.md
0007-webhook-retries.md
```
--------------------------------
### Example `lore docsets` output
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/commands.md
Example output from `lore docsets` showing docset grants, attributes, paths, and targets. `GRANTS` contains `ro`, `publish`, `rw`, or plugin-defined grants; `publish` means read access plus create/edit inside the docset's inbox, never delete. `ATTRIBUTES` may include `home`, `inbox`, and `alias`; aliases point to their canonical path in `TARGET`.
```text
DOCSET GRANTS ATTRIBUTES PATH TARGET
public ro - /docs/public -
backend publish,rw inbox /docs/backend -
home rw home /home/backend -
home rw alias /backend /home/backend
```
--------------------------------
### RBAC Quick Start: lore.json configuration
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/auth.md
Defines roles, docsets, and identities for role-based access control. Keyless visitors get read-only access to public docs, reviewers get read-only backend access, and engineers get read/write backend access. The engineer-home docset maps a home directory for the engineering-agent identity.
```json
{
"allow_keyless": true,
"unknown_identity": "deny",
"roles": {
"reviewer": {},
"engineer": {}
},
"docsets": {
"public": {
"paths": ["/docs/public"],
"access": {
"allow": { "guest": "ro", "reviewer": "ro", "engineer": "rw" }
}
},
"backend": {
"paths": ["/docs/backend"],
"access": {
"allow": { "reviewer": "ro", "engineer": "rw" }
}
},
"engineer-home": {
"paths": [{ "homes/engineer": "/home/engineer" }]
}
},
"identities": [
{
"name": "engineering-agent",
"public_key": "ssh-ed25519 AAAA...",
"roles": ["engineer", "reviewer"],
"home": "engineer-home"
}
]
}
```
--------------------------------
### Get passkey registration link via curl
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/deploy/render.md
On your own machine, set OPENLORE_URL and TOKEN (from the Render shell), then request a registration link. The printed /passkey/r/... link is valid for five minutes.
```shell
export OPENLORE_URL=https://openlore-abcd.onrender.com
export TOKEN=
curl -s "$OPENLORE_URL/api/shell" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"command":"passkey register --identity admin --name laptop"}' \
| jq -r .output
```
--------------------------------
### Install OpenLore skills via SSH
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/agents/shellm/openlore/SKILL.md
Creates the skill directories and downloads the OpenLore and housekeeping skill files from a remote server using SSH. Requires access to an OpenLore server and the OPENLORE_SSH environment variable.
```shell
mkdir -p .skills/openlore .skills/openlore-housekeeping
ssh $OPENLORE_SSH agents-shellm > .skills/openlore/SKILL.md
ssh $OPENLORE_SSH agents-shellm-housekeeping > .skills/openlore-housekeeping/SKILL.md
```
--------------------------------
### Run Caddy with Caddyfile
Source: https://github.com/aakarim/openlore/blob/main/examples/caddy-multi-port/README.md
Starts Caddy using the Caddyfile configuration. Requires sudo for ports 22, 80, and 443.
```shell
sudo caddy run --config Caddyfile
```
--------------------------------
### Initialize repository with lore init and git
Source: https://github.com/aakarim/openlore/blob/main/assets/skills/setup.md
Run from the parent directory to create a knowledge repository with the official `lore init` command, then enter it and initialize git. Use the agreed absolute path if the destination is elsewhere. Do not use `mkdir` or hand-written starter configs; init creates `openlore.yml` with defaults.
```shell
lore init -lore
cd -lore
git init
```
--------------------------------
### Start human-facing web view
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/usage.md
Starts the web interface on port 8080 by default. Use `--http-port` to change the port; `--http-port 0` disables the HTTP server. The page also serves the SSH host key at `GET /host-key`.
```shell
openlore ./docs
openlore --http-port 3000 ./docs
openlore --http-port 0 ./docs
```
--------------------------------
### Example output of lore meta briefing listing
Source: https://github.com/aakarim/openlore/blob/main/docs/recipes/weekly-briefing.md
Expected output format when listing briefings with their sources. Shows a single line per week with the briefing path, title, and source file paths.
```json
{"path":"2026-W41.md","title":"Weekly briefing, 2026-W41","sources":["../sessions/claude/3c90a1e2-7b4f-4d8e-9a21-5f6e7d8c9b0a.jsonl","../wiki/log.md"]}
```
--------------------------------
### GET /authorize
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/mcp.md
Initiates the OAuth authorization flow. The client opens this URL in a browser to start the authorization-code + PKCE flow, which then shows a passkey login page.
```APIDOC
## [GET] /authorize
### Description
Initiates the OAuth authorization flow. The client opens this URL in a browser to start the authorization-code + PKCE flow, which then shows a passkey login page.
### Method
GET
### Endpoint
/authorize
### Query Parameters
- **response_type** (string) - Required - Must be `code`
- **client_id** (string) - Required - The client identifier
- **redirect_uri** (string) - Required - The redirect URI (must be HTTPS or loopback)
- **state** (string) - Required - A random state value for CSRF protection
- **code_challenge** (string) - Required - base64url(sha256(verifier))
- **code_challenge_method** (string) - Required - Must be `S256`
- **scope** (string) - Required - Must be `full`
### Request Example
```
https://your-host/authorize?response_type=code&client_id=&redirect_uri=http://127.0.0.1:/callback&state=&code_challenge=&code_challenge_method=S256&scope=full
```
```
--------------------------------
### Connect via SSH
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/getting-started.md
Connects to the OpenLore server over SSH on port 2222. Once connected, agents can use shell-style commands in OpenLore's restricted interpreter (not Bash).
```shell
ssh -p 2222 localhost
```
--------------------------------
### Plain JSON HTTP API: curl examples for shell and commands
Source: https://github.com/aakarim/openlore/blob/main/assets/lore/mcp.md
Use these curl commands to interact with the plain JSON HTTP API, which is mounted on the HTTP server and backed by the same MCP server. The first runs a shell command via POST to /api/shell; the second lists available shell commands via GET /api/commands. Responses are JSON with 'output' and 'is_error' fields.
```shell
# Run a shell command
curl -X POST http://localhost:8080/api/shell \
-H 'Content-Type: application/json' \
-d '{"command": "grep -r auth /docs"}'
# => {"output":"...","is_error":false}
# List available shell commands
curl http://localhost:8080/api/commands
# => {"output":"Available commands:\n cat\n ...","is_error":false}
```
--------------------------------
### Install LangChain with MCP extra and provider package
Source: https://github.com/aakarim/openlore/blob/main/docs/start/agents/langchain.md
Installs langchain with the MCP extra and langchain-anthropic. Requires langchain[mcp] 1.4 or later; pip installs langchain, fastmcp, and langchain-anthropic.
```bash
pip install "langchain[mcp]" langchain-anthropic
```
--------------------------------
### lore init - Initialize a knowledge repository
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/lore-cli.md
Creates the directory if needed and writes openlore.yml with default ports, read-only serving, MCP and the JSON API enabled. Does not overwrite an existing openlore.yml, initialise Git, or create identities and access policy. Needs neither an existing repository nor a login.
```shell
lore init my-knowledge
```
--------------------------------
### lore.json identities, roles and docsets
Source: https://github.com/aakarim/openlore/blob/main/docs/start/create-knowledge-repository.md
Defines one role (engineers), one identity (alice) with a home, and two docsets. alice gets a home at /user/alice and can read and write /notes; anyone else sees neither. Add a public_key to the identity to allow SSH sign-in, or omit it for passkey/token sign-in.
```json
{
"roles": { "engineers": {} },
"identities": [
{ "name": "alice", "roles": ["engineers"], "home": "alice-home" }
],
"docsets": {
"alice-home": { "paths": [{ "user/alice": "/user/alice" }] },
"notes": {
"paths": [{ "notes": "/notes" }],
"access": { "allow": { "engineers": "rw" } }
}
}
}
```
--------------------------------
### Build with web UI using make distribution
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/building-from-source.md
Clones the repository and builds the web UI followed by the Go binary. `nix develop` is optional but provides the pinned Go and Node versions. `make distribution` builds the web UI first, then produces the `./openlore` binary.
```shell
git clone https://github.com/aakarim/go-openlore.git
cd go-openlore
nix develop # optional: provides the pinned Go and Node
make distribution # builds the web UI, then ./openlore
```
--------------------------------
### Import Claude project memory with lore agent import claude
Source: https://github.com/aakarim/openlore/blob/main/docs/start/agents/start-claude-code.md
Run from a project directory to sync Claude Code's CLAUDE.md, rules, and auto memory into the server so other agents and teammates read the same context. See the linked guides for sharing with a team or keeping personal ~/.claude files private.
```shell
lore agent import claude
```
--------------------------------
### Create an MCP-only server with NewMCPServer
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/usage.md
Builds an MCP-only server from any OpenLore filesystem, here ./docs with *.md and *.txt allowed. Sets the server name and instructions for agents.
```go
fs := openlore.NewDirFS("./docs", openlore.FilesConfig{
Allowed: []string{"*.md", "*.txt"},
})
srv := openlore.NewMCPServer(fs,
openlore.WithMCPServerName("Company Knowledge Repository"),
openlore.WithMCPInstructions("Use grep and cat to explore the docs."),
)
```
--------------------------------
### Run guided import with --project flag
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/import-claude-project.md
Run from the project directory to import Claude Code project instructions and auto memory. Requires a completed `lore login` and a project with a `CLAUDE.md` or memory directory under `~/.claude/projects/`. The `--project` flag offers only project-related groups and ticks the instructions and memory groups by default.
```shell
lore agent import claude --project
```
--------------------------------
### Create style docset with budgets (lore.json)
Source: https://github.com/aakarim/openlore/blob/main/docs/recipes/coding-style-guide.md
Defines the 'style' docset with two budget rules: 'guide-length' caps any guide.md at 300 lines, and 'page-size' caps every Markdown file at 2,000 estimated tokens (excluding guides). The 'curator' role has read-write access, 'staff' has read-only. Identities include 'adil' (curator, staff) and 'coding-agent' (staff). Requires a running server with writes enabled and auth_file pointing at a lore.json.
```json
{
"roles": {
"curator": {},
"staff": {}
},
"docsets": {
"style": {
"paths": ["/style"],
"access": { "allow": { "curator": "rw", "staff": "ro" } },
"config": { "edit": ["curator"] },
"rules": {
"guide-length": { "match": ["*/guide.md"], "use": "size/lines", "with": { "max": 300 } },
"page-size": { "match": ["**/*.md"], "exclude": ["*/guide.md"], "use": "size/tokens", "with": { "max": 2000 } }
}
}
},
"identities": [
{ "name": "adil", "public_key": "ssh-ed25519 AAAA…", "roles": ["curator", "staff"] },
{ "name": "coding-agent", "public_key": "ssh-ed25519 AAAA…", "roles": ["staff"] }
]
}
```
--------------------------------
### Embed docs in a binary with make dashboard-build and go build
Source: https://github.com/aakarim/openlore/blob/main/README.md
Place documentation in assets/lore/ and build. The resulting binary contains the docs and serves them read-only at /docs when run with no directory argument. The make dashboard-build step is optional to include the web UI.
```shell
make dashboard-build # optional: include the web UI
go build -o my-docs ./cmd/openlore
```
--------------------------------
### Initialize repository with lore init and git init
Source: https://github.com/aakarim/openlore/blob/main/docs/start/create-knowledge-repository.md
Creates the folder acme-lore with a default openlore.yml and initializes Git. For an existing folder without openlore.yml, run lore init inside it instead.
```shell
lore init acme-lore
cd acme-lore
git init
```
--------------------------------
### Install SFTP FS extension for VS Code
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/editors.md
Install the SFTP FS extension for VS Code to browse and edit OpenLore files over SFTP. Use this instead of Microsoft's Remote - SSH, which is not compatible with OpenLore.
```shell
code --install-extension LewLie.sftpfs
```
--------------------------------
### lore init
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/lore-cli.md
Initializes a new knowledge repository by creating the directory if needed and writing an openlore.yml configuration file with default settings. It does not overwrite existing configurations or set up Git or access controls.
```APIDOC
## lore init
### Description
Initializes a new knowledge repository by creating the directory if needed and writing an openlore.yml configuration file with default settings. It does not overwrite existing configurations or set up Git or access controls.
### Usage
`lore init [directory]`
### Parameters
- **directory** (string) - Optional - The directory to initialize. Defaults to the current working directory.
### Request Example
```shell
lore init my-knowledge
```
```
--------------------------------
### default_cwd key
Source: https://github.com/aakarim/openlore/blob/main/docs/reference/openlore-yml.md
Directory a session starts in. Default is /openlore.
```yaml
default_cwd: /docs
```
--------------------------------
### Run guided import with --personal
Source: https://github.com/aakarim/openlore/blob/main/docs/how-to/import-claude-memory.md
Run the guided import with `--personal` from any folder; `lore` finds your knowledge repository through your last `lore login`. `--name` sets the prefix of the source names; the default is the current directory's name followed by `-claude`.
```shell
lore agent import claude --personal --name claude
```
--------------------------------
### Configure identities, roles, and docsets in lore.json
Source: https://github.com/aakarim/openlore/blob/main/docs/start/agents/start-ssh.md
Maps an SSH public key to an identity with a role and docset access. Anonymous sessions use the built-in `guest` role. The `backend-agent` identity gets `rw` access to `/backend`; `guest` gets `ro` to `/public` and `/backend`.
```json
{
"allow_keyless": true,
"unknown_identity": "allow",
"roles": { "backend": {} },
"docsets": {
"public": {
"paths": ["/public"],
"access": { "allow": { "guest": "ro", "backend": "ro" } }
},
"backend": {
"paths": ["/backend"],
"access": { "allow": { "backend": "rw" } }
}
},
"identities": [
{ "name": "backend-agent", "public_key": "ssh-ed25519 AAAA…", "roles": ["backend"] }
]
}
```
--------------------------------
### GET /api/commands
Source: https://github.com/aakarim/openlore/blob/main/docs/concepts/transports.md
Lists the commands supported by the server, equivalent to the `list_commands` MCP tool.
```APIDOC
## GET /api/commands
### Description
Lists the commands supported by the server, equivalent to the `list_commands` MCP tool.
### Method
GET
### Endpoint
/api/commands
### Response
#### Success Response (200)
- **commands** (array of strings) - List of command names.
```