Metadata-Version: 2.4
Name: leaxp
Version: 0.2.0
Summary: Agentic experience kit — package and distribute agent skills as portable .xp files.
Project-URL: Homepage, https://leaxp.com
Project-URL: Repository, https://github.com/vunone/leaxp
Project-URL: Issues, https://github.com/vunone/leaxp/issues
Author: Leaxp Authors
License-Expression: Apache-2.0
License-File: LICENSE.txt
Keywords: agent,ai,experience,llm,mcp,rag,skill
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio>=4.7.0
Requires-Dist: fastembed>=0.8.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: tomli-w>=1.1.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# Leaxp

![Leaxp](https://github.com/vunone/leaxp/blob/main/docs/assets/hero.webp?raw=true)

[![CI](https://github.com/vunone/leaxp/actions/workflows/ci.yml/badge.svg)](https://github.com/vunone/leaxp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/vunone/leaxp/branch/main/graph/badge.svg)](https://codecov.io/gh/vunone/leaxp)
[![PyPI](https://img.shields.io/pypi/v/leaxp.svg)](https://pypi.org/project/leaxp/)
[![Python](https://img.shields.io/pypi/pyversions/leaxp.svg)](https://pypi.org/project/leaxp/)
[![License](https://img.shields.io/pypi/l/leaxp.svg)](https://github.com/vunone/leaxp/blob/main/LICENSE.txt)

> **Lea**rn -> e**xp**erience — 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

```bash
pip install leaxp
```

That's it — search runs on a small local ONNX embedding model ([fastembed](https://github.com/qdrant/fastembed)); no torch, no services, no API keys.

## Quickstart

```bash
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](https://github.com/vunone/leaxp/blob/main/CLAUDE.md) for the package architecture overview and [AGENTS.md](https://github.com/vunone/leaxp/blob/main/AGENTS.md) for coding-agent ground rules. Release notes live in [CHANGELOG.md](https://github.com/vunone/leaxp/blob/main/CHANGELOG.md); the release process in [RELEASING.md](https://github.com/vunone/leaxp/blob/main/RELEASING.md).

## Development

```bash
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](https://github.com/vunone/leaxp/blob/main/LICENSE.txt).
