Skip to content
Portwright
GitHub

A tool-use memory layer for AI agents

Agents forget how tools work. Portwright keeps the notebook.

Portwright makes your agent read a short note about a tool before it touches that tool: the procedure that works today, what failed last time and which steps need a human. Markdown files and the Python standard library, nothing else. One git clone.

macOS, Linux 
PW="$HOME/tools/portwright"
git clone https://github.com/foxion37/portwright.git "$PW"
"$PW/bin/portwright" client install codex
"$PW/bin/portwright" check
"$PW/bin/portwright" preflight github

Needs git, bash and Python 3.9 or later. Change codex to your client, such as claude-code or cursor.

View on GitHub Read the full story (Korean)
Version
v4.0.2
License
MIT, free
Runs on
macOS and Linux
Needs
git, bash, Python 3.9+

Smart agents still repeat old mistakes.

Hand an agent a GitHub deploy or an API connection and it acts like it is day one. It asks you to paste a token when a connector could do the work, walks you through a dashboard path that has moved and hits the permission error you already fixed. Without memory, it fails the same way twice.

preflight

One call before it touches the tool.

Your agent runs portwright preflight with the tool's name and gets everything at once: a state such as READY or DERIVE REQUIRED, the procedure note, active lessons and a freshness mark. The agent still does the work with its own CLI, MCP or API. Portwright only advises, and it hands steps such as OAuth approval to you.

Fresh public clone
$ "$PW/bin/portwright" preflight github
READY: github
Profile: (none) no profiles defined
Procedure: services/github.md
Freshness: unknown -> verify-required (no evidence supplied (rule 3))
Tier: confirm
Active Lessons: 3

Three notes

Procedure, Lesson, Profile.

Three kinds of short Markdown notes do the work.

  • Procedure: the steps that are correct today, and which of them only a human can do.
  • Lesson: what was tried, the confirmed root cause and the corrected move.
  • Profile: which GitHub account, secret source and database this project uses.
Portwright cover: a paper plane flies over search, run and analyze, above a memory layer
Cover image from the portwright repository (made with ChatGPT).

Fills itself

New tools get a note the first time.

There is no pre-written library of 500 tools. When your agent meets a tool with no note, Portwright reports DERIVE REQUIRED and the agent drafts the current procedure from the official docs. A person reviews the draft before it enters the cache, after checks for secret patterns and unconfirmed causes.

What preflight reports
  1. READYA note exists. Read it, then act
  2. DERIVE REQUIREDNo note yet. Draft one from official docs
  3. fresh | stale | unknownFreshness, never fresh without evidence
  4. auto | confirm | forbidAdvisory tier. Unknown falls back to confirm

Three promises keep it honest.

And a few more things that make it safe to leave running.

  1. Freshness never flatters

    fresh needs evidence. Without it the answer is unknown plus "verify first", and unknown is never promoted to fresh.

  2. The tier is advice, not a gate

    Portwright reports auto, confirm or forbid and stops there. Your client's own permission prompt enforces it.

  3. The cache fills itself

    Knowledge arrives because it was needed, not because someone pre-wrote it.

  4. Profile router

    A profile binds each project folder to its GitHub account, env source and databases, so preflight answers for the right account.

  5. Guarded updates

    portwright update pulls new notes with git pull --ff-only and re-checks stale ones.

  6. Backups first

    Client install writes a .bak backup before it touches your existing settings.

It joins the agent you already use.

Eight clients are supported, including these.

Before you start

Clone once. Stop repeating the same failure.

Clone the repository, connect your client and run preflight before the next tool call.

View on GitHub Read the full story (Korean)