pdsa

Run your PDSA loop as graph memory. The expected outcome you set in Plan is judged in Study by an LLM — and every cycle accumulates into a per-project graph an AI agent can recall.

Get Started View on GitHub

# Windows x64 · Linux x64 · macOS (Apple Silicon) npm i -g @webnori/pdsa pdsa version

How it works

One command per step. One graph that never forgets.

A PDSA cycle is four commands. plan makes the LLM commit to a verifiable expected outcome; study judges the result against it (met / partial / unmet); act decides whether to reinforce. Every step is written to a per-project Kùzu graph DB — so the learning compounds across runs.

A pdsa cycle: plan sets an expected evaluation, do executes, study is judged by an LLM, act reinforces, and every step is recorded to the graph DB. — Plan → Do → Study → Act, with a REINFORCES feedback edge — recorded to the graph on every step.

Features

Built for AI agents that learn on the job

Study, not Check

The third step asks what did we learn?, not did it pass?. An LLM judges the result against the Plan’s expected evaluation and records a verdict: met partial unmet.

Graph memory, per project

Every Plan/Do/Study/Act node and REINFORCES edge lands in an in-process Kùzu graph DB at {LocalAppData}/pdsa-cli/{project}/graph.kuzu. Read it back with Cypher; visualize it with pdsa view.

Recall as a metric

Progress isn’t vibes — it’s an expectation hit-rate (met / cycles-with-a-verdict), surfaced in status, eval, and the viewer.

Bring any LLM

OpenAI API keys, keyless open-weight endpoints (ollama · vLLM · LM Studio), GPT OAuth, Codex, or your already-logged-in Claude Code (claude -p). No LLM? Inputs are still recorded.

One native binary

A Native AOT single executable with Akka.NET and Kùzu bundled — shipped to npm as @webnori/pdsa for Windows, Linux, and macOS (Apple Silicon).

Drop-in for Claude Code

Ships a ready-to-use skill (.claude/skills/pdsa). Say “pdsa” in a session and the agent runs its work as Plan→Do→Study→Act, accumulating graph memory. pdsa init installs it anywhere.

Architecture

A shared core, three consumers, pluggable foundations

The reusable AkkaGraphLoop.Core (PDSA engine + Kùzu interop) is shared by the CLI, the graph viewer, and the learning samples — sitting on the Kùzu embedded graph DB and pluggable LLM providers.

The pdsa CLI, graph viewer, and samples all build on AkkaGraphLoop.Core, which sits on the Kùzu graph DB and pluggable LLM providers.

See it

Watch the memory grow

pdsa view serves a local, self-contained viewer of the recorded graph — Study nodes colored by verdict, REINFORCES edges, a project switcher, and a live hit-rate badge.

pdsa view — project switcher, verdict-colored Study nodes, a REINFORCES edge, and a hit-rate badge. — `pdsa view` — verdict-colored Study nodes, REINFORCES edges, and an expectation hit-rate badge.

Install pdsa npm one-liner, or run from a dev tree.

Your first cycle Plan → Do → Study → Act, end to end in five minutes.

LLM providers & auth OpenAI, open-weight, OAuth, Codex, Claude CLI.

CLI reference Every command, flag, and exit code.

Community

Built at Akka Labs

pdsa grew out of akka-graph-loop — a learning project on Akka.NET Streams graphs. Come say hi, ask questions, and follow along.

Akka Labs — Facebook group The Akka research community (아카 연구소). Discussion, questions, and updates.

psmon — LinkedIn Connect with psmon, the creator of pdsa and akka-graph-loop.