### 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. ```