A versioned context build system for AI.
Lorepack compiles documents, spreadsheets and project files into an immutable build that AI clients can read through MCP, HTTP or a bounded export. Inspect what went in, review changes between versions, activate a known build and roll back without rebuilding.
Where it fits · Quick start · CLI · Studio · Limits · Documentation
Use Lorepack when the context your AI depends on changes, and you need to control which version it reads.
- Coding agents: share one context build across Claude Code, Codex, VS Code or another MCP client.
- Teams: review specifications, runbooks, policies and research before activating an update.
- Documents and spreadsheets: preserve document structure and query typed tables with source coordinates.
- CI and deployment: validate and package a reproducible context artifact, with optional Cloudflare deployment.
The build is the source of truth. Search and task context read that build and carry source locators. Model-facing tools are read-only; developers control builds, activation and deployment through the CLI or Studio. Lorepack does not decide which document is true.
On the v0.1 Linux x64 reference machine (Ryzen 9 3900X, Node.js 24.18.1), warm lexical search p95 was 21.45 ms and task-context assembly p95 was 199.96 ms over 50,000 chunks. The measured gates are 250 ms and 1,500 ms. These are reference measurements, not latency guarantees across machines. See the performance report and artifacts for the workload, machine and limits.
A separate provisional, reported-only experiment on an Apple M1 Pro (8,520 chunks) measured warm-search p95 at 12.78 ms for Lorepack's full runtime and 0.29 ms for direct SQLite FTS5. The SQLite index starts from already parsed chunks and returns ranked rows; it does not measure build, provenance, context assembly, typed tables, activation or rollback. See the comparison method and results.
Core concepts · Worked examples
Installation and first build · Install from source
Requires Node.js >=24.19.0 <25. Install the alpha from npm's next channel and open a
folder of documents:
npm install -g @lorepack/cli@next
lorepack dev ./my-docsdev builds the folder, watches for changes, opens Studio and prints the HTTP and MCP
endpoints. Reads continue from the active build during rebuilds.
No Python, Docker, native add-on, model download, API key or account is required.
Connect an installed AI client:
lorepack connect claude-codeThe command previews its configuration change and asks before writing it. Verification checks the intended build and a cited source read; the client's own trust prompt is separate.
Claude Code · Codex · VS Code · Other MCP clients
Command reference · Complete walkthrough · Real demo output
Build, search with citations, compare versions, roll back and serve. Static, reduced-motion demo.
In an existing project, compile a candidate while keeping the current build active:
lorepack plan
lorepack build --no-activate
lorepack validate
lorepack diff <active-build-id> <candidate-build-id>
lorepack activate <candidate-build-id>
lorepack mcp --follow-activeUse the full build IDs printed by the commands. build activates on success unless you
pass --no-activate. lorepack rollback selects the previously active build without
recompiling sources.
mcp --follow-active serves the reviewed active build and reports source freshness without
rebuilding it. See MCP serving modes for other startup policies.
lorepack search "deployment rollback"
lorepack export --task "Prepare a cited rollback checklist"Search returns source excerpts. Task exports assemble bounded context with provenance, cited table schema references and explicit omissions. Table rows stay behind separate query reads. Exports do not call a model or generate summaries.
| Task | Command |
|---|---|
| Inspect sources and warnings | lorepack inspect sources, lorepack inspect warnings |
| Serve an existing build | lorepack serve, lorepack mcp --active-only |
| Create a portable build | lorepack pack --out context.lorepack |
| Deploy to Cloudflare | lorepack deploy cloudflare |
Use --json for scripts and CI. The CLI reference covers every
command, option and shell-completion setup.
Studio tour and workflow recordings
Run lorepack dev ./my-docs to open the local inspector.
Studio overview: active build, freshness, agent endpoints and warnings. More workflows are in the Studio tour.
- Overview and Sources: see the active build, freshness, indexed files, exclusions and warnings.
- Playground: assemble task context and inspect selections, omissions and equivalent CLI, HTTP and MCP requests.
- Tables: inspect schemas and sample rows, then run bounded read-only queries.
- Versions: compare builds, activate, roll back and package a retained version.
- Diagnostics: check the environment, watcher and detected AI clients.
Review task context before copying it to an agent. Static screenshot · Full Studio tour.
Studio exposes the same build lifecycle as the CLI. Use the tour for route-by-route screenshots and detailed workflows.
Format guide · Parser budgets · CSV limits · v0.1 limitations · Compatibility and measurements
Markdown, plain text, source code, HTML, DOCX, text-layer PDF, CSV and XLSX are supported. Lorepack preserves the structure each parser exposes and reports unsupported or excluded content. Spreadsheet formulas are retained as text and never executed. Formula and conversion evidence distinguishes saved values from unevaluated formulas.
v0.1 does not include OCR, image understanding, PPTX, SaaS connectors, multi-user tenancy or embeddings in the default install. Retrieval is lexical; authority and precedence are user-declared hints. Review the limitations before choosing a production integration.
Documentation index · Architecture map
| Topic | Read next |
|---|---|
| Build lifecycle | Build orchestration, validation, watch behavior |
| Reproducibility | Build identity, package format |
| Context and tables | Ranking and delivery limits, table storage, receipts |
| Runtime access | MCP, HTTP, SDK, reader lifetimes |
| Deployment | Cloudflare setup, deployment and cleanup |
| Evidence and performance | Benchmark methodology, compatibility evidence |
Start with CONTRIBUTING.md and AGENTS.md. Source installation, testing and CI, including policy fixtures and dependency decisions live in the contributor docs. Cloudflare CI requires credentials; see the integration test setup.
For environment issues, include lorepack doctor --json, your OS and Node version.
Report vulnerabilities through SECURITY.md.