PyRecall
Local project memory and correction learning for Python workflows.
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
- You provide a rejected approach and a preferred approach.
- PyRecall stores the correction and distills a named skill.
- Later
recall/get_contextranks that skill into the result set with BM25 + overlap scoring. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.