lore

A standalone, cross-project learning base for AI agents and humans.

lore keeps durable product and technical learnings in one place, each tagged to the project it came from — so insight earned on one repo improves the next. It's a single static binary that is three things at once:

• a CLI — lore add, lore search, lore list, …
• an MCP server — lore mcp, so Claude Code, Claude Desktop, Cursor, and any other MCP client can capture and recall learnings as native tool calls
• a web UI — lore ui, a browsable, themeable view of everything (with illustrations)

No runtime to install, no CGO (pure-Go SQLite), one file of data you own.

---

Why

Agents forget everything between sessions and between repos. Notes rot in scattered markdown. lore gives an agent a durable, queryable memory of lessons — not tasks, not transcripts — split cleanly into:

• product — how the product should behave; principles; information architecture; domain decisions.
• technical — code structure, stack, build/tooling, gotchas, security invariants, conventions.

Each learning records its source project, so lore search on a new repo surfaces what you already worked out on an old one.

Install

# from source (Go 1.24+)
go install github.com/hadelekan/lore@latest

# or grab a prebuilt binary from the Releases page and put it on your PATH

Data lives outside the binary, in your OS config dir (%APPDATA%\lore\lore.db on Windows, ~/.config/lore/lore.db on Linux, ~/Library/Application Support/lore on macOS). Override with $LORE_DB (a file path) or $LORE_HOME (a directory). See lore path.

CLI

lore add "A saved item must snapshot, not reference, an ephemeral source" \
  -c product -p my-app -t persistence,feeds -b "RSS keeps only N items; a pointer dangles…"

lore search ssrf            # match title/body/tags/project
lore list -c technical      # filter by category / -p project / -t tag
lore show 12                # one learning + its illustrations
lore projects               # per-project counts
lore export -p my-app       # markdown (or --format json) for reuse elsewhere
lore asset 12 --path diagram.png --caption "the flow"   # attach an illustration
lore import old.db          # pull learnings from another lore/knowledge DB

lore rm 12                  # move #12 to the trash (soft delete; recoverable)
lore restore 12             # bring it back out of the trash
lore trash                  # list what's in the trash
lore purge --all            # empty the trash now (or --days N for the policy)
lore rm 12 --permanent      # skip the trash and delete for good

Deleting & the trash

Deletion is temporal: lore rm (and the web UI's delete) move a learning to a trash, where it stays fully recoverable with lore restore. A retention policy then permanently purges anything older than 30 days (override with $LORE_TRASH_RETENTION_DAYS); the purge runs on lore ui startup and on demand via lore purge. Trashed learnings are hidden from the library, search, and all counts.

Bodies are markdown; pass them with -b, --body-file, or piped stdin.

MCP — wire it into your agent

lore mcp speaks MCP over stdio. It advertises capture/recall instructions, so the model applies the workflow (honor @learn, keep product vs technical separate, tag the source project, recall before deciding) without extra prompting.

Claude Code:

claude mcp add lore -- lore mcp

Claude Desktop / Cursor (mcpServers in the client config):

{
  "mcpServers": {
    "lore": { "command": "lore", "args": ["mcp"] }
  }
}

Tools exposed: lore_create, lore_search, lore_list, lore_get, lore_update, lore_delete, lore_projects, lore_tags, lore_stats, lore_attach_asset, lore_add_quiz.

Each article is attributed (the authoring model + an author handle, defaulting to $LORE_AUTHOR), can embed a Mermaid diagram (rendered in the reader), and — by the server's standing instruction — ships with an exhaustive quiz you can take in the web UI.

Directing captures in a session — you don't have to wait for it to notice something: @learn <note>, "note this as a learning: …", "write a lore article on <topic>", or "capture what we figured out about X". The model researches, writes the article + diagram, and attaches the quiz.

Web UI

lore ui --open       # http://localhost:4180

Filter by category / project / tag, full-text search, and open any learning to read its rendered markdown and illustrations. Light + dark themes. Reads the same database the CLI and MCP server write, so captures appear live on refresh. The reader has an "On this page" section outline (click to jump, highlights as you scroll), prev/next navigation, share, and per-article delete (into the trash).

AI rewrite (bring-your-own-key)

With an LLM key configured, the reader shows an AI rewrite action that asks the model to improve an article — tightening the concept → worked-example → diagram structure and adding a Recommended reading (real sources with authors + links) and Related section. You review the proposal in a preview and save (or discard) it; nothing is changed until you accept. Enable it with any OpenAI-compatible endpoint:

export LORE_LLM_API_KEY="sk-…"                        # required (enables the feature)
export LORE_LLM_BASE_URL="https://api.openai.com/v1"  # optional (OpenAI, OpenRouter, Groq, local, Anthropic-compat…)
export LORE_LLM_MODEL="gpt-4o-mini"                   # optional
lore ui

Capturing from other AI chats

Not on Claude Code? The web server exposes a token-guarded POST /api/learnings so ChatGPT (Custom GPT Action), Gemini, or a phone can post a learning to a hosted lore — plus a universal "paste format" that works anywhere. See docs/INTEGRATIONS.md.

LORE_INGEST_TOKEN="a-secret" LORE_AUTHOR="you" lore ui   # enables POST /api/learnings

Build

The web UI is TypeScript (internal/web/app.ts), compiled by bun into internal/web/assets/app.js, which the Go binary embeds. The compiled output is committed so go install works without bun.

bun run build:web           # internal/web/app.ts -> internal/web/assets/app.js
bun run check:web           # type-check with tsc --noEmit
go build -o lore .          # single binary, embeds the web UI, no CGO
go test ./...

License

MIT © Adelekan Adedokun