Built into Penstock · v0.5.3
Your AI starts from why, not from zero.
Generating code got cheap. Knowing why it is the way it is did not. Penstock keeps the reasons as plain files you own, and puts them in front of the model before it writes.
An agent can write an implementation in seconds. What it cannot see in the code is why the last one was written differently, which approach was tried and dropped, and what broke the time before. That knowledge lives in people's heads, old pull requests and chat threads, and it is the part that makes reviewing someone else's diff slow. Penstock writes it down as you work: each piece of work becomes an episode that records what was asked, what was decided and why, what was refused and why, what was learned and what is still open. Beliefs that hold up become facts, each one quoting the episode it came from. Before every model call, Penstock recalls the ones that matter, under rules you set, and its log shows exactly what it recalled.
Why: these folders are this project's own build memory, not every deployment's.
Refused: walking the workspace once per signature glob.
Why: one walk per assemble() is enough and an UncheckedIOException must not abort the turn.
A codebase index and your own record answer different questions.
More of a developer's day now goes on reading diffs they did not write and deciding whether they are good enough. The diff shows what changed. Whether it repeats a mistake the team already made, or undoes a choice made on purpose, depends on reasons that were never in the code.
Tools that index a codebase answer what calls what and what a change might break, and some also mine the reasons recorded in its commits and design notes. That is useful work on the code. Penstock keeps a different record: yours, across every project, written down as part of the work, with nothing entering it until you have reviewed it, and with rules for which project may see which part. It lives in files you can read, correct and own.
| Your record, in Penstock | |
|---|---|
| Scope | You: every project, plus the facts, conventions and principles that hold across them |
| Source | The work as it happened: the issue, the pull request, and the Decided:, Refused:, Learned: and Open: lines in commit messages |
| What makes it true | Your review: a script drafts from the evidence, nothing enters until you commit it, and each fact quotes the episode it came from |
| Who sees what | Rules per project: a public project never loads a private one's cards, and every load or refusal is logged, and on the audit log with database storage |
| When the model changes | Unchanged: plain YAML files with a published schema, not tied to any model |
| With an index | An index and the record answer different questions, and an agent can use both. Penstock also reads the workspace: a pattern loads when its file signatures match the code in front of it. |
Small cards, in files you own
Every card is a YAML file with a JSON Schema, kept in a folder or a private git repository of yours. Nothing enters it without your review. Shipping since v0.4.0.
- Episodes
- One per piece of work: asked, built, decided and why, refused and why, learned, open.
write-episode.shdrafts it from the issue, the pull request and the commit messages; from Claude Code or Claude Desktop,draft_episodewrites one new draft and never overwrites (v0.5.0); since v0.5.3 it waits indrafts/, and recall does not read it until you move it intoepisodes/. v0.4.0 - Facts
- One belief each, with a confidence, the date it was last confirmed, and provenance that quotes the episode it was learned from.
consolidate.shproposes new, confirmed or superseding facts; you decide. A changed belief supersedes the old one rather than overwriting it, so the record keeps what you used to think and when that changed. v0.4.0 - Patterns
- How a kind of thing was built, with the release it was last verified against; a pattern behind the newest release is flagged as stale. v0.4.0
- Boundaries
- Each card carries a visibility, and your
memory.yamlgives each project an audience. A public project never loads a private one's cards, and a credential-shaped value stops a write before anything is saved. v0.5.0
Penstock keeps its own record in the open: 5 episodes, 14 facts (one superseded) and 1 pattern, last verified against v0.3.0 and so flagged stale, in the repository at v0.5.3. The format is in the shipped docs.
Before the model writes a line
In a Penstock turn, code chooses what the model sees, not the model. The choice is deterministic: trigger words, scope and recency, never an embedding or another model call.
Matching facts, the project's latest episodes and the patterns its files fit, in one block of at most 12,000 characters, ahead of the model call. With memory on (v0.4.0).
The block asks the model to end each plan decision with the card it rests on, or to mark it as an assumption with a question for you, and to propose an episode rather than write a fact (v0.5.2). Nothing checks the markers yet; you read them.
Every section loaded or kept out, with the reason, and every card loaded, logged, and with database storage shown in the web UI's Audit view (v0.5.0).
The same record reaches Claude Code and Claude Desktop: java -jar penstock-0.5.3.jar --mcp runs a local MCP server whose recall builds the same block under the same project rules (v0.5.0). There the host decides when to call it. Setup is in the README.
Planned: a companion that speaks from your record
Planned, and named here so the direction is plain (penstock#93). You name the companion once, in a card. From then on it opens with where things stand, answers from your record before the web and says which it used, cites the card behind each decision, and asks one question when the record is silent, then writes the answer down. Its voice and its judgement come from principles you hold as cards, with provenance, in domains you choose.
It is a projection of the record, not a separate model. When the record improves, the companion sharpens, and a change in its voice is a dated line you can read. Nothing about it lives anywhere you cannot read, edit or delete.
Where it stands
Nothing on this site is announced before it has run. This is the honest state.
- Shipped
- Episodes, facts and patterns with schemas and a checker; drafting from the work's own evidence; recall before every model call; project audiences; the MCP server for Claude Code and Claude Desktop; the cite-or-assume and propose-don't-write rules. In Penstock v0.5.3. live
- Its limits
- The record knows only what was written down: work done before you started keeping it is not in it. Recall reads the current message, not the whole conversation. Memory is off by default in the web and IDE modes and on for
--mcp. Reviewing drafts happens in the files for now. Penstock itself should run on your own machine, not on a network, until it clears the stranger test. - Planned
- The persona (#93). A script that checks the citation markers (#92). A review inbox and a memory browser in the web UI (#108, #107). Hosted sessions and Claude Cowork reading the record from a pod (#89). planned
- Licence
- Apache 2.0, free for any use including commercial.