Lore

The operating substrate for hybrid human + AI teams. — getlore.ai · npm

Lore lets humans and AI agents act coherently from shared, current truth — collapsing coordination cost so a small hybrid team moves at the speed of a much larger one.

Every input flows through it. Every decision is recorded in it. Every agent boots from it. Every human consults it. Sources are eternal evidence with citations; briefs are the synthesized current state at every level of concern. Humans and agents share one interface (MCP) and one substrate.

The full thesis is in docs/VISION.md. What's below is how to use what ships today.

Quick Start

npm install -g @getlore/cli

# Setup (API keys + login)
lore setup

# Add a source directory (interactive prompts)
lore sync add

# Sync and search
lore sync
lore search "user pain points"

What ships today

• Workspaces & projects — Workspaces are the ACL/identity boundary; projects are the synthesis unit, each with a living brief
• Tags — Cross-cutting attribute axis (per-org conventions, retrieval refinement; not the primary organizing axis)
• Project briefs — Living synthesis per project, versioned, staleness-aware, used as warm-start for agents
• Hybrid search — Semantic + keyword with Reciprocal Rank Fusion, time-weighted
• Agentic research — Claude iteratively explores the substrate, synthesizes findings with citations
• Auto-routing — LLM proposes (project, tags) at ingest time; explicit destinations always win
• MCP integration — 9 tools, equally usable by humans (CLI/TUI) and agents
• Repo-attached working context — .lore/ working copies in code repos for Claude Code, Cursor, Codex, etc.
• Universal sync — Two-phase (free discovery, processing only for new files), hash-deduplicated across machines
• Universal formats — Markdown, JSONL, JSON, PDF, images, CSV, HTML, and more
• Multi-tenant auth — Email OTP, Postgres RLS for data isolation

Toward the thesis

The current product is a research knowledge repository. The architectural direction (per VISION.md) is:

• A third scope layer (workstream / track / area) below project, with its own briefs
• Content types as true primitives — decisions ratchet, plans have status, questions resolve, information decays
• Inherited brief stack as the agent's working context (workspace → project → workstream)
• Synthesis cascade — material lower-scope changes ripple upward
• Authority enforcement at the MCP layer for multi-agent safety
• Workspace-level brief — the company's constitution, top of every agent's stack

These are additive to what's already in place; most foundations exist.

MCP Configuration

One-click install:

Run npx @getlore/cli setup first to configure API keys and sign in. The MCP server reads your config automatically — no env vars needed.

Manual config — add to your MCP client config (.mcp.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "lore": {
      "command": "npx",
      "args": ["-y", "@getlore/cli", "mcp"]
    }
  }
}

CLI Commands

| Command | Description | |---------|-------------| | lore setup | Guided configuration wizard | | lore auth login | Sign in with email OTP | | lore workspace info / list | Show or list workspaces | | lore sync | Sync all configured sources | | lore sync add | Add a source directory | | lore sync repair | Repair generated data-repo metadata conflicts | | lore search <query> | Hybrid search (--projects, --tags, --tags-all, --workspace) | | lore research <query> | Agentic deep research | | lore browse | Interactive TUI browser | | lore brief <project> | Show / generate / list / history / diff project briefs | | lore context add <project> [<project2> …] | Attach project .lore/ working copies to the current repo | | lore context list / status / replace / remove | Manage repo-attached context | | lore status | Where am I, what's pending — unified state view | | lore diff [id] | Show a change diff (≈ git diff) | | lore changes apply [--all\|<id>] | Publish reviewed edits to canonical Lore (≈ git push) | | lore changes discard [--all\|<id>] | Drop a working-copy edit, refresh the snapshot (≈ git restore) | | lore changes merge <id> | LLM-assisted three-way merge for a conflict (≈ git merge) | | lore docs list / reproject | List documents; re-route a source | | lore docs extract-backfill | Backfill typed chunks for sources that have none yet | | lore projects | List projects | | lore cost | Token usage + dollar cost (--since, --feature, --workspace, --by) | | lore mcp | Start MCP server |

One Lore, Many Surfaces

Lore is reachable through MCP, CLI, the lore browse TUI, direct editor workflows, and project .lore/ working copies. The shared contract is:

• Canonical Lore is the approved truth
• MCP/CLI/TUI write canonical Lore only through explicit user-directed actions
• Project .lore/ working-copy edits are proposals until reviewed and approved
• Approved changes update canonical Lore, re-index one source, and become visible everywhere

Project Context For Code Agents

Use lore context add from a code repo to give Claude Code, Codex, Cursor, or another agent local project knowledge:

cd ~/workspace/ridekick
lore context add ridekick

This creates repo/.lore/context.md, editable source snapshots, a manifest, and local agent instructions. By default, Lore adds all non-deleted sources for the project; pass --limit <n> only when you deliberately want a smaller working copy. Context uses copied snapshots by default, not symlinks. Edits inside .lore/sources/ are proposed changes; canonical Lore only updates after lore changes apply. Use lore changes discard <id> to drop a local proposal and refresh the snapshot from canonical.

context add also registers the repo in ~/.config/lore/context-targets.json, so the Lore daemon keeps clean snapshots fresh after sync cycles. Local edits are never overwritten by refresh; they remain proposals and become conflicted if canonical Lore changed too. A repo's .lore/ can attach multiple projects (lore context add p1 p2 p3); each gets its own namespaced sources/base directories under .lore/sources/<project>/ and .lore/base/<project>/. Use lore context list to see repos with Lore context and the last refresh result.

context add writes .lore/.gitignore so generated snapshots stay out of the host repo by default. Most users should leave .lore/ uncommitted; add .lore/ to the repo root .gitignore too if you want the rule to be obvious. See Project Context Working Copies for the full workflow.

To turn off repo-local context, run lore context remove from the repo root. It unregisters the repo from daemon refresh, removes only the generated .lore/ working copy, and refuses to discard active proposals unless you pass --force.

Requirements

• Node.js 18+
• OpenAI API key (embeddings)
• Anthropic API key (metadata extraction, auto-routing, brief generation, research)
• Lore account (free — sign up via lore auth login)

How Sync Works

1. Discovery (free) — Finds files, computes SHA256 hashes, checks for duplicates
2. Processing (new files only) — Claude extracts metadata, OpenAI generates embeddings, stores in Supabase

Same content on different machines produces the same hash — no duplicate processing.

Lore Cloud (Supabase) is the canonical sync layer. Git in LORE_DATA_DIR is optional local history; generated cache files such as sources/.paths.json and deleted-hashes.json are ignored and can be rebuilt. If the data repo gets into a Git conflict, run:

lore sync repair

The daemon reports repair-needed Git state but still refreshes project .lore/ working copies from Lore Cloud.

Async Git Push

Hot ingest/edit/delete paths return immediately; the daemon batches accumulated changes into a single commit/push every 30 seconds. lore sync status shows Pending pushes: N (oldest 2m ago) when the queue isn't empty. Pass --sync-push (or set LORE_SYNC_PUSH=1) for the inline-push escape hatch — useful in CI / scripts.

The status output also shows the daemon's package version. After npm install -g @getlore/cli upgrades the CLI, the running daemon detects the version drift within ~60s, SIGTERMs itself, and launchd's KeepAlive respawns it from the new dist/ — no manual lore sync restart needed. Set LORE_DISABLE_VERSION_RESTART=1 to disable for local dev. On non-launchd hosts, the SIGTERM still fires; respawn needs a supervisor (systemd, etc.) or a manual lore sync start.

Multi-machine and multi-agent writes

Two writers (different machines, different agents, or human + agent) hitting the same source simultaneously won't silently overwrite each other. The losing write gets a typed conflict response:

Source <id> was modified by another writer since you started this approval.
Pull latest changes and run `lore changes merge` to merge, then approve again.

MCP ingest action 'update' returns a structured conflict block on race-loss so agents pattern-match and retry without scraping error messages.

Spend Control

lore cost shows token usage and dollar cost by feature, workspace, or window. A daily Anthropic spend cap is on by default as a backstop — LORE_MAX_DAILY_TOKEN_SPEND_CENTS=200 ($2/day); override with any positive integer (cents) or set 0 to disable. Past the cap, new LLM calls are refused before the SDK runs (LLMBudgetExceededError); an 80%-of-cap warning fires once per process. It gates brief generation, sync, the auto-router, the chunk extractor, research, and lore ask. Brief auto-update + auto-router degrade gracefully when the cap trips. See docs/COST_DISCIPLINE.md for the cost-discipline methodology.

Typed-chunk extraction

Lore can extract typed chunks (decisions, commitments, quotes, …) from each source. LORE_EXTRACTION_ENABLED=true turns on auto-extraction at ingest and sync time (default off); lore docs extract-backfill mines the sources that already exist. Extraction is tier-aware — producer-stamped skip sources never call the LLM — and inherits the daily spend cap. See docs/AUTO_EXTRACT.md.

Tunable env vars:

• LORE_BRIEF_DEBOUNCE_MS (default 60000) — project brief auto-update window
• LORE_BRIEF_DEBOUNCE_WORKSTREAM_MS (default 30000) — workstream brief window
• LORE_PENDING_PUSH_FLUSH_MS (default 30000, min 5000, 0 disables) — daemon's batched-push cadence
• LORE_CONTEXT_REFRESH_TIMEOUT_MS (default 60000) — hard timeout on context refresh to release the write lock if the network gets stuck
• LORE_SYNC_PUSH=1 — disables async push for the current process (legacy inline behavior)

Agent Platform Install

Lore works with any agent that supports MCP. Use lore skills install or install directly from your platform's registry.

Claude Code

# From plugin directory (once approved)
/plugin install lore

# Or install directly from GitHub
/plugin install https://github.com/getlore-ai/lore/tree/main/plugins/claude-code

# Or via Lore CLI
lore skills install claude-code

Gemini CLI

# From Extensions Gallery
gemini extensions install lore

# Or install directly from GitHub
gemini extensions install https://github.com/getlore-ai/lore --path plugins/gemini

# Or via Lore CLI
lore skills install gemini

Codex CLI

# Add MCP server
codex mcp add lore -- npx -y @getlore/cli mcp

# Install skill
lore skills install codex

OpenClaw

# From ClawHub
clawhub install lore

# Or via Lore CLI
lore skills install openclaw

License

MIT © PersonL, LLC. Lore is a product of PersonL, LLC.