Skip to main content

PyRecall

CI PyPI

Local project memory and correction learning for Python workflows.

PyRecall animated demo: harvest, learn from diff, recall with why

PyRecall keeps durable notes about your repository, turns corrections into reusable skills, and serves them back through a CLI or a stdio tool bridge that compatible coding tools can call.

No cloud account. No network calls for recall. Everything stays in .pyrecall/ inside your project.

Replay the same ~30s learn → recall session locally:

# Unix
bash examples/demo.sh

# Windows PowerShell
./examples/demo.ps1

Recording tips: docs/DEMO.md. Animated preview: docs/demo.svg.

Why

Coding tools forget project preferences between sessions. You correct the same mistake twice. PyRecall records the correction once and surfaces it the next time the same topic comes up — especially for Python testing, typing, packaging, and style conventions.

Install

pip install pyrecall-cli

This installs the pyrecall command and the pyrecall Python package.

If pyrecall is not found on Windows after install:

python -m pyrecall doctor
python -m pyrecall --help

Or add your user Scripts folder to PATH, then open a new terminal.

For local development:

pip install -e ".[dev]"

Requires Python 3.10+.

Quick start

cd your-python-project
pyrecall init
pyrecall harvest
pyrecall index
pyrecall setup-host
pyrecall learn --rejected "unittest.TestCase" --preferred "pytest assert + fixtures" --reason "Repo standard"
pyrecall recall "how should tests be written"

Free-form corrections

pyrecall learn --blob "os.path.join => Path / 'name'"
pyrecall learn --blob "avoid: bare except | prefer: except ValueError as exc"

Commands

Command Purpose
pyrecall init Create .pyrecall/, seed defaults, host rules + workflow
pyrecall harvest Turn README / CONTRIBUTING / AGENTS bullets into conventions
pyrecall index Index docs and Python module signals
pyrecall watch Re-index when docs/config/Python files change
pyrecall remember Store a decision / convention / note
pyrecall learn Distill a correction (--blob, --diff)
pyrecall recall Search (--tag, --under, --why)
pyrecall consolidate Merge near-duplicate correction skills
pyrecall skills List learned skills
pyrecall forget Deactivate a skill
pyrecall packs List/install stack packs (fastapi, django, …)
pyrecall setup-host Write host rules, bridge JSON, AGENTS.md section
pyrecall workflow Print or write the before/after-edit checklist
pyrecall doctor Check PATH / store health
pyrecall playbook Write SKILLS.md from active skills
pyrecall stats Show store counts
pyrecall export / import-data Backup and restore JSON
pyrecall serve Run the stdio tool bridge

Skill packs

pyrecall packs list
pyrecall packs install fastapi
pyrecall packs install django
pyrecall packs install sqlalchemy
pyrecall packs install ruff
pyrecall packs install uv
pyrecall packs install mypy
pyrecall packs install celery
pyrecall packs install pytest-asyncio

Learn from a patch

pyrecall learn --diff path/to/fix.patch

Scoped recall

pyrecall recall "error handling" --under src/api

Consolidate duplicates

pyrecall consolidate

Keep memory fresh

# one-shot
pyrecall index

# poll and re-index on change (side terminal)
pyrecall watch

Sticky workflow for hosts

pyrecall setup-host        # HOST_RULES.md + bridge JSON + AGENTS.md
pyrecall workflow          # print checklist
pyrecall harvest           # import conventions from project docs

setup-host writes .pyrecall/HOST_RULES.md (required get_context before edits, learn_correction on user fixes) and ready-to-copy bridge configs with your project cwd.

Stdio tool bridge

Compatible coding tools that speak JSON-RPC over stdio can attach PyRecall as a local tool server.

Full guide: docs/BRIDGE.md

Quick connect

pip install pyrecall-cli
cd your-python-project
pyrecall init
pyrecall serve

Add this to your host tool config (restart the host afterward):

{
  "pyrecall": {
    "command": "pyrecall",
    "args": ["serve"],
    "cwd": "/absolute/path/to/your/python-project"
  }
}

Windows / PATH-safe variant:

{
  "pyrecall": {
    "command": "python",
    "args": ["-m", "pyrecall", "serve"],
    "cwd": "C:/Users/you/projects/myapp"
  }
}

Ready-made files: bridge.client.json · bridge.mcp.json · bridge.windows.json

Tools exposed

Tool Purpose
get_context Required before edits — conventions + skills (+ why)
search_memory Ranked search; optional tags filter
learn_correction Required on user corrections — durable skill
add_memory Store a decision / convention / note
list_skills List active skills
install_pack Install fastapi / django / sqlalchemy / ruff pack
harvest_docs Import convention bullets from project docs
project_stats Store counts

How learning works

  1. You provide a rejected approach and a preferred approach.
  2. PyRecall stores the correction and distills a named skill.
  3. Later recall / get_context ranks that skill into the result set with BM25 + overlap scoring.
  4. Skill hit counts increase when they are retrieved, so useful rules rise over time.

All ranking is local. There are no model downloads and no external APIs.

Storage layout

.pyrecall/
  config.json
  store.db
  WORKFLOW.md
  HOST_RULES.md
  bridge.mcp.json
  bridge.client.json
  bridge.python.json
  index/

Add .pyrecall/store.db to .gitignore if you do not want binary state in git. Export JSON when you want a reviewable backup.

Python defaults

pyrecall init seeds practical skills such as:

  • prefer pytest over unittest
  • type-hint public APIs
  • pathlib over os.path
  • context managers for I/O
  • no bare except:
  • pyproject-first configuration

Optional packs add FastAPI, Django, SQLAlchemy, and ruff conventions via pyrecall packs install ….

Development

pip install -e ".[dev]"
pytest
ruff check src tests

See CHANGELOG.md for release history, docs/LAUNCH.md for the public launch checklist, and docs/SPONSORS.md for funding setup.

License

MIT

Metadata

Release files for pyrecall-cli 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyrecall-cli 0.5.0
File Size Uploaded Provenance Actions
pyrecall_cli-0.5.0.tar.gz 1.2 MB With provenance Details for pyrecall_cli-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyrecall-cli 0.5.0
File Interpreter ABI Platform Actions
pyrecall_cli-0.5.0-py3-none-any.whl Python 3 none any Details for pyrecall_cli-0.5.0-py3-none-any.whl

Total release size: 1.2 MB

Release files / pyrecall_cli-0.5.0.tar.gz

Download URL pyrecall_cli-0.5.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
434289b1abc5c4fe4c84b9b67781967524f557f86333d6c804b2dc93fa61bbbf
BLAKE2b-256 checksum
How to use checksums
c9f8a15e71a981e7fe2293ce026a485fb4c27223cb0656f126bf0135eab1b50e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.

Transparency log

Release files / pyrecall_cli-0.5.0-py3-none-any.whl

Download URL pyrecall_cli-0.5.0-py3-none-any.whl
Size 41.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e6024f4a1f61839898d53310d4129cba2d9fcf2ba9735223c4dfaa0dc66f7d1
BLAKE2b-256 checksum
How to use checksums
fcc8e644bb9289f8fdc81b5130792084055982a6e5a729a93e3a2011bb9814f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.

Transparency log

Security for pyrecall-cli 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyrecall_cli-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page