Leaxp

Learn -> experience — a bridge sharing experience between agentic sessions. Package and distribute agent skills, knowledge, and experience as portable .xp files.

Leaxp gives every project a searchable knowledge database (.xp/ — Markdown records indexed by a small local embedding model) and exposes it to coding agents through three MCP tools: recall, expand, remember. Knowledge is learned by your own agent CLI (claude / codex) — no external LLM API, no keys. Smaller context, cheaper inference, model-agnostic.

Status: MVP — file-based installs work end-to-end; GitHub and registry sources are coming.

Install

pip install leaxp

That's it — search runs on a small local ONNX embedding model (fastembed); no torch, no services, no API keys.

Quickstart

exp use --with claude       # wire MCP + hooks, create .xp/, leaxp.toml, leaxp.lock
exp learn --goal "onboard new contributors"   # drive claude/codex to distill the codebase
exp share -o my-project.xp  # pack .xp/local/ into a shareable archive

# on another machine / project
exp install -f my-project.xp          # unpack into .xp/share/<name>/ + index
exp install -f my-project.xp --self   # ...or into .xp/local/ for editing
exp sync                              # reindex .xp/ after editing records by hand
exp exec "create stripe subscription" # print the raw recall output for a query
exp mcp                               # (run by your agent) serve recall/expand/remember

Once wired, agents get an initial memory recall on their first prompt and can:

• recall(query, subquery?, limit?) — search records; returns scored titles + expected outcomes grouped into <package> blocks, low-relevance hits filtered out. Conventional records come fully expanded as <rule> entries in a separate <conventions> block.
• expand(id | [ids]) — fetch full Markdown bodies, one record or several at once
• remember(title, description, content, id?, convention?) — write or update knowledge; pass convention=true to record a one-paragraph rule that renders in full on every matching recall

Concepts

• Record — one Markdown file with YAML frontmatter under .xp/local/ (git-tracked, yours) or .xp/share/<pkg>/ (installed, git-ignored). Record titles follow [action] [package|entity] [subject?] — e.g. create stripe subscription — so searches and titles speak the same language.
• Convention — a record flagged convention: true: a one-paragraph rule (naming, structure, which tool/skill to use) that recall renders in full, no expand needed. Searched separately from regular records.
• Index — index.npy + index.json; exactly one vector per Markdown-heading breadcrumb (Stripe API > Webhooks > Error Handling), searched by cosine similarity with a relevance floor so agents never wade through noise. Recall groups results by package, labeling each with its description (from leaxp.toml for local, from the install manifest for shared packages).
• .xp file — zip of record Markdown + a sha256-signed manifest. Embeddings are recomputed locally on install, so the same pack works with any embedding model.

Project structure

See CLAUDE.md for the package architecture overview and AGENTS.md for coding-agent ground rules. Release notes live in CHANGELOG.md; the release process in RELEASING.md.

Development

uv sync                                  # create venv, install deps
uv run pre-commit install                # enable hooks
uv run ruff check . && uv run pyright    # lint + typecheck
uv run pytest --cov                      # tests with coverage
uv run exp --help

License

Apache-2.0 — see LICENSE.txt.