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 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, low-relevance hits filtered out
• expand(id | [ids]) — fetch full Markdown bodies, one record or several at once
• remember(title, description, content, id?) — write or update knowledge

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.
• 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.
• .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.

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.