Metadata-Version: 2.5
Name: scriptflow-procedural-memory
Version: 0.3.0
Summary: Procedural memory for LLM agents: record solved tasks, compile them into replayable skills, run them without reasoning again
Project-URL: Homepage, https://github.com/GrappinoRoot/scriptflow
Project-URL: Issues, https://github.com/GrappinoRoot/scriptflow/issues
Project-URL: Changelog, https://github.com/GrappinoRoot/scriptflow/blob/main/CHANGELOG.md
Author-email: Antonio Carmellino <tonycarmellino@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,agent-memory,caching,llm,mcp,procedural-memory,skills,tool-calling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
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.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# procedural-memory

**Give your AI agent a memory of how it solves tasks.**

`procedural-memory` saves successful tasks as reusable skills. When a similar request comes in, it replays the saved steps instead of asking the LLM to solve the same problem again.

**Solve it once. Reuse it next time.**

```
USER REQUEST
      │
 intent + parameters ← one cheap classification call
      │
 ┌────┴─────┐
 │  STORE   │
 └────┬─────┘
   ┌──┴──┐
MATCH    NO MATCH
   │          │
SKILL       AGENT → success check → compile → STORE
   │          │
   └────┬─────┘
      RESULT
```

## How it works

1. Your agent receives a request.
2. The library checks whether a matching skill already exists.
3. If a skill matches, it replays the saved tool calls.
4. If no skill matches, your agent solves the task.
5. If the task succeeds, the library saves it as a reusable skill.

## Features

- **Save reasoning costs** — reuse previous solutions instead of solving the same task again.
- **Works with any LLM** — you provide your own `classify` and `call_tool` functions.
- **No dependencies** — only Python 3.10+ is required.
- **Sync and async** — supports both synchronous and asynchronous functions.
- **Safe by design** — skills contain JSON tool calls, not executable code.
- **Human-readable skills** — inspect and edit saved procedures manually.
- **Keep control** — your existing permissions, confirmations, rate limits and auditing still apply.

Skills are learned only from successful executions. A skill is not saved if it depends on a fixed identifier or contains unused request parameters.

## Install

```bash
pip install scriptflow-procedural-memory
```

## Documentation

See [SPEC.md](SPEC.md) for the skill format and technical details.

## License

MIT