Procedural memory · field guide

Runbooks

Save a how-to once. Your agents pull it back when they hear a matching trigger phrase. mnueron tracks how often each one is used and how reliable it's been — so drifted procedures stop being silent time-bombs.

Open the runbook manager Jump to examples

What is a runbook?

A runbook is a saved how-to— a list of steps you'd otherwise re-type or re-explain to your AI agent every time you do a recurring task. Each runbook has a title, a summary, a list of trigger phrases, and an ordered list of steps. Optional per-step command, check, and notes fields turn the runbook from notes into something you (or an agent) can mechanically execute.

Procedural memory is the bit Mem0 and Letta don't have. Their memory remembers what you said; runbooks remember how you do things.

Agents pull them automatically

When an agent's input matches one of your trigger phrases, the runbook flows into the context window — no re-explaining.

Reliability tracking built in

Click ✓ Worked or ✗ Failed every time you run a runbook. A green/amber/red chip on each card tells you which procedures have drifted.

Multiple triggers per runbook

One runbook can be reached by 'deploy mnueron', 'ship to vercel', 'push the fix' — whichever phrasing your agent or future-you uses.

GIN-indexed for fast lookup

Trigger arrays are indexed with Postgres gin (text[]_ops). Multi-phrase matching is sub-millisecond even across thousands of runbooks.

When to write a runbook

A reliable test: have I explained this to an AI agent more than twice this week? If yes, write it down once and let the agent recall it.

Deploy + release procedures (push, rollback, hotfix)
Onboarding checklists (new contractor, new dev environment)
Recovery playbooks (the DB ran out of connections, the API key rotated)
Multi-step workflows that mix shell, dashboard, and SQL
Single-shot tasks you'll never repeat — not worth the storage
Things that change daily — they'll drift faster than you can keep up

Anatomy of a runbook

Every runbook is one row in the procedural_memories table (migration 030). The shape:

Field	Type	What it does
title	text	Human label. Unique within your org (case-insensitive).
summary	text · optional	One-line description. Shown on the card and in agent retrieval.
trigger_phrases	text[]	Phrases that retrieve this runbook. GIN-indexed for fast multi-trigger match.
steps	jsonb	Ordered list of { description, command?, check?, notes? } objects.
success_count	int	Bumped when you POST { outcome: 'success' } on the runbook.
failure_count	int	Bumped on failure. Used to compute the green/amber/red reliability chip.
last_used_at	timestamptz	Stamped on every outcome record. Surfaces 'most recently used' sorting.

Per-step fields

Each step is a JSON object inside the steps array:

description	What this step does. Required.
command	Shell or SQL command to run. Optional. Rendered in a code block.
check	How to verify the step worked. Optional. Shown as a 'Check:' caption.
notes	Free-form caveats, gotchas, or alternatives. Optional. Rendered as italic.

Reliability tracking

Every time you finish running a runbook, click ✓ Worked or ✗ Failed. The counter on the row updates, and the chip changes color based on the success rate over its lifetime:

≥ 90% success

Green — the procedure is still accurate. Trust it.

60-90% — drifting

Amber — failures have crept in. Open the runbook and update the steps.

< 60% — broken?

Red — this procedure no longer matches reality. Rewrite or archive it.

Untested runbooks (0 runs) show a neutral slate chip. The whole point of the counter is that silent drift is the worst kind— a runbook that used to work but now subtly doesn't is more dangerous than one that's obviously broken. The chip surfaces that gap before it bites.

Three worked examples

Copy any of these into the runbook manager and adapt the commands for your environment. Each one is a real recurring task in a mnueron-shaped project.

Example #1

Push mnueron changes to Vercel

Stage files, commit, push to main; Vercel auto-deploys.

deploy mnueronship to vercelpush the fix

1
Open PowerShell at the mnueron repo root
```
cd C:\Mnueron\ai-boilerplate-pro
```

Clear any stale git lock left by the Linux sandbox

Remove-Item .git\index.lock -Force -ErrorAction SilentlyContinue

3
Stage the files you changed
```
git add <files>
```
4
Commit with a conventional-commit-style message
```
git commit -m "feat(area): what changed"
```
5
Push — Vercel auto-deploys main
```
git push origin main
```
Check: Vercel dashboard shows 'Building' on the new commit within 10s
6
Wait ~90s for green build, then verify the live URL
Check: curl -sI https://www.mnueron.com/ | head -1 → HTTP/2 200

Example #2

Apply a Supabase migration

Paste a SQL file from supabase/migrations into the SQL editor, verify with the probe.

apply migrationrun sql migrationrun the migration

1
Open Supabase → SQL Editor → New Query
2
Paste the contents of the next migration file (lowest-numbered file in supabase/migrations not yet applied)
Migrations are append-only; don't edit a file that's already been applied in prod.
3
Click Run — verify all statements succeed
Check: Result panel shows 'Success. No rows returned' OR a returning row from the sanity probe.
4
If a sanity probe is at the bottom of the migration, paste + run it separately too

Commit the migration file to the repo so it's not lost

git add supabase/migrations/<file>.sql && git commit -m 'feat(db): describe what it does'

Example #3

Debug a 402 on /api/memories save

Memory save returned 402 (free-tier limit, server-key quota, or storage cap). Diagnose which.

402 on savememory save failedwhy is save 402

1
Open Vercel function logs → look for the failing POST /api/memories invocation
Check: Find the response body — the 'error' field is one of: memory_quota_exceeded, storage_quota_exceeded, llm_quota_exceeded
2
If memory_quota_exceeded → free-tier 500-memory cap reached. Upgrade plan or wait for next month.
3
If storage_quota_exceeded → free-tier 100MB cap. Same fix — upgrade or delete old memories.
4
If LLM gate (auto-synopsis / entity extraction) is gated, the save itself still succeeds — only the LLM fields are skipped
Confirm by checking if the row landed: SELECT id FROM memories ORDER BY created_at DESC LIMIT 1;

API reference

For SDK or curl access, runbooks live under /api/procedural. All endpoints are tenant-scoped via your bearer token; the org id is derived from the token.

GET/api/procedural

List runbooks. Sorted by COALESCE(last_used_at, updated_at) DESC.

qfree-text search against title + summary

triggermatch runbooks containing this trigger phrase

limit1..500, default 50

offsetpagination, default 0

POST/api/procedural

Create a runbook. Body: { title, summary?, trigger_phrases?, steps? }. Returns the new row including id, success_count: 0, failure_count: 0. Fails with 409 if a runbook with the same title (case-insensitive) already exists in the org.

GET/api/procedural/[id]

Fetch one runbook by id.

PATCH/api/procedural/[id]

Update fields. Body accepts any subset of: title, summary, trigger_phrases, steps, metadata. Only fields you include are touched — PATCH { title } won't wipe steps.

DELETE/api/procedural/[id]

Permanent delete. Returns { deleted: true }.

POST/api/procedural/[id]

Record an outcome. Body: { outcome: "success" | "failure" }. Bumps the matching counter, stamps last_used_at to now(). This is what the ✓ Worked / ✗ Failed buttons in the dashboard call.

Frequently asked

Are runbooks paid-tier only?

No. Free tier can create and use runbooks. The auto-extraction path (asking an LLM to generate a runbook from a transcript) is a future paid feature, but manual creation is free for everyone.

How are trigger phrases matched — exact, fuzzy, or semantic?

Today it's case-insensitive contains match — trigger_phrases @> ARRAY['ship to vercel']in Postgres, GIN-indexed for speed. Once a hosted embedder lands, we'll add a semantic-similarity path so “deploy the app” also retrieves a runbook tagged “push the fix.”

Can I share a runbook with my team?

If your org has multiple users (Team / Enterprise plan), every member of the org sees every runbook in that org. Per-runbook visibility (private / team / public) is on the roadmap — same pattern we already use for entities.

What if my runbook has a secret in it?

Use metadata.byok_*_key or environment-variable placeholders like $ANTHROPIC_API_KEY in the commandfield rather than the literal value. mnueron's server-side redactor scans content for known secret patterns and strips them before save — but the cleanest rule is never to put a secret in a runbook in the first place.

Can an agent execute the runbook automatically?

Not yet. Today, an agent retrievesthe runbook (via trigger-phrase match) and renders it as context — the human or the agent then runs each step. An “execute” path that runs the command field through a sandbox is on the roadmap.

Save your first runbook

Take the recurring task you've explained to an AI agent the most in the last week. Write down the steps. Tag it with how you'd phrase it next time. That's the entire workflow.

Open the runbook manager