This repository moved to https://github.com/sainzs/agent-workbench/tree/main/packages/reckoner. History was preserved via subtree, and this repository is frozen at its last version.
"Because we separate like ripples on a blank shore."
The memory and policy layer of the Random Access agent toolchain.
Every coding agent forgets everything between sessions. It makes the same type error, misuses the same API, breaks the same test - every time, from scratch. Brilliant for five minutes, then gone.
Reckoner is a pi package that closes the feedback loop. When the agent makes an error, it catches it, fixes it, and records the pattern. Next session, that lesson is in its context. The agent compounds its competence over time instead of resetting to zero.
auto-verify catches error → agent fixes it → lesson recorded → next session avoids it
That's it. One loop. Everything else supports it.
The agent edits code. It has full access to your filesystem, shell, and tools.
Auto-verify catches errors. After every turn that edits files, the agent checks its own work — type errors, test failures, and diagnostic issues. If something breaks, it sees the error and fixes it before telling you it’s done.
Lessons are recorded automatically. When auto-verify catches an error, the pattern
is written to .pi/memory/mistakes.md - what file, what error, whether it was fixed.
No manual action needed. The loop closes itself.
Next session starts with context. Recent lessons, architectural decisions, user preferences, and open questions are injected into the system prompt. The agent picks up where it left off. Mistakes are prioritized - they're the most valuable signal.
Memory is human-readable. Everything is stored as markdown files you can open, edit, and version. Not a vector database. Not an opaque embedding store. Your files, your history, your control.
The loop is the thesis. These are the organs that support it:
| Capability | How |
|---|---|
| Structural search | AST-aware code search and refactoring via ast-grep. |
| Plans before editing | Plan mode (Ctrl+T) blocks edits. The agent reads and thinks first. |
| Safety net | Git state checkpointed before and after every turn. /undo to restore. |
| Web research | web_search and web_fetch for docs and APIs. Research before reinventing. |
| Codebase awareness | repo_map for structural overview. Understand before you edit. |
| Guardrails | Blocks writes to .env, ~/.ssh, and key files. Dangerous commands require confirmation. |
| Principles | Behavioral guidelines injected every session. Read before acting, smallest safe change, verify before done. |
reckoner ships four terminal themes, each a love letter to a real tube — an amber EXECT-100, a green VT640 radar, a navy VT100 war room, and a teal winamp HUD. One philosophy binds them: one phosphor, four brightnesses. Hierarchy comes from luminance, the way real CRTs worked; syntax highlighting stays inside the phosphor family.
| theme | tube | glow |
|---|---|---|
reckoner-exect |
EXECT-100 / DEC VT520 | amber |
reckoner-scope |
DEC VT640 | P1 green |
reckoner-wopr |
VT100 | navy + cyan |
reckoner-darkspace |
dark.spaceAMP | teal wireframe |
/theme reckoner-exect # inside pi, after /reload
Global install, the full gallery with live color previews, the token table, and the design philosophy live in the phosphor family.
They pair with the harness footer — the braille ink system in
extensions/harness-footer.ts: a three-cell field that animates whatever the
harness is doing (the tape advances one frame per token chunk; a beam sweeps
while it searches; ink falls during a compaction), a CONTEXT well of remaining
room with a crest running along its surface, a STEPS trail of progress. Labels are silkscreen, values are the
phosphor. Motion is bound to real events, so an idle footer is perfectly still
and costs nothing — the whole vocabulary.
extensions/nerd-footer.ts is a separate live footer loaded directly from this
checkout by the user's ~/.pi/agent/settings.json. It renders the current path
on the left and a context gauge, last-turn token counts, model, and extension
statuses on the right using Nerd Font glyphs.
git clone https://github.com/sainzs/reckoner.git
cd reckoner
npm install
npm run verify:self| Requirement | Why |
|---|---|
| pi 0.64+ | the agent runtime |
rg (ripgrep) |
codebase scanning |
fd |
file discovery |
JINA_API_KEY |
web search - free tier |
pi -e .Runs the package in-place for that session.
cd your-project && piReckoner loads automatically.
- Start in plan mode (
/planorCtrl+T) - let the agent read and understand - Switch to build mode (
/buildorCtrl+T) - now it can edit - Auto-verify catches errors - the agent fixes them before reporting done
- Lessons are recorded automatically - patterns persist to next session
/undoif something goes wrong - checkpoints restore the working tree
The canonical task→model policy lives in docs/orientation-policy.md and prompts/model-routing.md. The matching skill is a thin wrapper around that shared policy, and opencode.json pins the same mappings for OpenCode agents.
| Command | What it does |
|---|---|
/plan |
Switch to read-only mode. Agent can read but not edit. |
/build |
Switch to full mode. Agent can edit. |
/undo |
Restore last git checkpoint. |
/verify |
Toggle verification. Sub-commands: run, last, baseline. |
/memory |
Show what the agent remembers. recent for last entries. |
/lessons |
Inspect stored lessons. Sub-commands: repeated, unresolved, promoted, file <path>. |
/metrics |
Show learning-loop metrics. Sub-commands: recent, repeated. |
/orient |
Open orientation overlay (also Ctrl+Shift+O). |
/inject |
Show last prompt injection trace and budget. |
/task |
Show current task plan. |
/tone |
Switch theme. Options: random (default), dusk, factory, plus the four phosphors in the phosphor family. |
/snapshot |
Refresh and show workspace context. |
/guardrails |
Show or toggle safety guardrails. |
| Tool | What it does |
|---|---|
remember |
Save a note to persistent memory |
recall |
Search memory for past notes |
repo_map |
Structural overview of the codebase |
sg_search |
Structural code search + rewrite preview via AST patterns |
web_fetch |
Fetch any URL as clean markdown |
web_search |
Search the web |
Stored as markdown in .pi/memory/ (per-project) or ~/.pi/agent/memory/ (global).
.pi/memory/
├── mistakes.md # auto-learned + manual lessons
├── codebase.md # architecture, patterns, decisions
├── journal.md # chronological session notes
├── preferences.md # how you like things done
└── questions.md # open unknowns to revisit
Two layers:
- Storage - append-only, human-readable. Write liberally. The files grow. That's fine.
- Injection - curated subset in the system prompt. Only the most relevant entries. Mistakes first.
These are your files. Open them. Edit them. Delete things that are wrong. They're yours.
Your memory lasts exactly as long as this context window. When the session ends, you forget everything. This is the fundamental condition of every coding agent, and everything else follows from it.
Reckoner exists to fight that. Not with a vector database or an embedding pipeline. With markdown files and a feedback loop. Simple tools, used well, compounding over time.
The name comes from Radiohead's In Rainbows. A reckoner figures things out. It accounts for things. It reasons through the mess.
reckoner is the memory layer of the Random Access agent toolchain — four small packages that compose into one maintainer surface:
| Package | Layer | What it does |
|---|---|---|
| santiagosainz-skills | Workflow | Portable maintainer skills: review, planning, debug, verify, handoff |
| reckoner | Memory | Agent memory, auto-verification, and guardrails |
| registro | Reporting | Agent work report CLI and dashboard |
| random-access-themes | Design system | OLED-black themes and tokens shared across the toolchain |
reckoner themes are the phosphor siblings of the OLED-black tokens — four retro tubes in the phosphor family, usable standalone or with the harness footer.