A local-first persistent memory layer for AI coding sessions. It captures the gotchas, decisions and dead-ends your code can't tell an agent — and replays them into the next Cursor / Claude Code / Copilot session, so the same wrong turn never happens twice.
The problem
You spend 90 minutes teaching an agent that your auth API returns 200 even on errors. Next session it writes if (response.ok) all over again. The model didn't get worse — it has no memory. Code changes daily; what the system actually does under those edits — the invariants, the constraints, the things that bit you last week — code can't tell you.
Each session re-reads the code and re-infers the obvious, burning tokens and wall-clock.
The same wrong turn someone hit yesterday gets made again — the gotcha never persisted.
"Why opaque tokens, not JWTs?" — the rationale lived in a chat that's gone.
System overview
Clients talk to infernoflow over several interchangeable transports; a small deterministic core reads and writes a single on-disk memory store and keeps the IDE rule files current. No service, no daemon, no network in the default path.
amp_* tools are exposed over MCP, VS Code LMT and as CLI aliases — one product, one disk file, multiple transports. Pick whichever fits your setup; all paths write to the same .ai-memory/.The loop
infernoflow closes the cold-start loop in four stages. Most of it happens without you: the MCP-aware agent writes entries; the CLI and hooks back it up; the next session boots warm.
amp_write; a Cursor prompt-hook backstops it deterministically.file:line, tags, timestamp, a stable AMP id.branches/<branch>.jsonl (git-tracked) or global.jsonl (personal). Travels with the branch.Data flow
How a single finding travels the whole system — from the moment it surfaces to the next session that starts warm because of it.
Steps 1→3 are capture (the AI writes, hooks back it up); 4→6 are restore (the core regenerates the rule files, the next session reads them at boot). The green nodes are the durable on-disk state; the cyan nodes are what the agent reads and writes.
Data model — the AMP protocol
AMP (Agent Memory Protocol) is the vendor-neutral format at the core. One append-only JSONL record per memory, with a stable id so any AMP-Full client can reference it.
// one line in branches/<branch>.jsonl { "id": "amp_01KYVXSNMAWCQ9…", // stable AMP id "type": "gotcha", // see types → "msg": "API returns 200 on errors", "file": "server/src/api.ts", "line": 42, "tags": ["auth","http"], "ts": "2026-07-31T08:12:03Z", "agent": "infernoflow", // who wrote it: user | infernoflow "detail": "amp_01KY…" // optional → details/<id>.md }
| Type | Meaning | Auto-prune? |
|---|---|---|
gotcha | An invariant that bit you | never |
decision | A standing choice + rationale | never |
pattern | How things are done here | never |
bookmark | Named session resume point | never |
attempt | A fix that failed | 30d |
note | Transient observation | 30d |
detection | Auto-detected signal | 30d |
Rotation archives stale note/attempt/detection to archive/ — invisible to reads, still on disk. The four durable types are the knowledge you logged infernoflow for.
The lean index (msg + file:line) is what gets injected and stays cheap. A rich detail body lives in details/<id>.md, loaded on demand via readDetail() and never injected into rule files — you pay for the body only when you open it.
Storage layout
.ai-memory/ ├── branches/ │ ├── main.jsonl project truths (git-tracked) │ └── feature-auth.jsonl branch work (git-tracked) ├── details/ │ └── amp_01KY….md tier-2 bodies (on demand) ├── archive/ │ └── sessions-2026-07.jsonl rotated-out ├── global.jsonl personal prefs (gitignored) ├── handoff.md generated by `switch` └── amp.json config
merge=union on the branch JSONLs means concurrent commits from two machines merge cleanly — no conflict resolution.refresh.Transports & integration
| Tool | Reads from | Writes via |
|---|---|---|
| Claude Code | CLAUDE.md | MCP (amp_write) |
| Cursor | .cursorrules | MCP + beforeSubmitPrompt hook |
| GitHub Copilot (VS Code) | .github/copilot-instructions.md | VS Code LMT + MCP — both wired |
| Windsurf | .windsurfrules | MCP (manual wiring) |
When the server is wired, the agent calls these directly. The six amp_* tools follow the AMP MCP spec — vendor-neutral — and are mirrored as CLI aliases name-for-name.
Injection & refresh
The agent reads the IDE's own rule files at boot. infernoflow owns a marked-off block inside each; your manual edits outside the markers are never touched.
<!-- infernoflow:start --> 🔥 gotcha @ api.ts:42 — 200 on errors, check body 🔥 decision @ auth.ts — opaque tokens, revocable <!-- infernoflow:end -->
Injected content is paid for on every turn, so defaults are lean: 4 entries, 5 commits, 200-char truncation, a compact ~3-line protocol. Tunable in amp.json (maxEntries, protocolStyle, targets).
infernoflow refresh — manual rebuild; --targets controls which files carry the block.Note: a running MCP server loads once at session start — after an upgrade, quit & reopen the IDE. infernoflow doctor flags a runtime/CLI version mismatch.
Capture pipeline
A protocol block in the rule files teaches the agent when to call amp_write: on a gotcha hit, a decision, a failed fix, a pattern.
A Cursor beforeSubmitPrompt hook scans your prompt for triggers (!!, retry, not working, bookmark this) and writes the entry deterministically when the AI doesn't.
A bookmark with no note reads Claude Code's on-disk transcript, distills the last ~40 turns to markdown, stores it as context — no model call.
sk-, ghp_, -----BEGIN) are rejected at the AMP writer, so credentials never reach a git-tracked file.The second product
One CLI, two products. Session Memory (the default, memory-first) is everything above. Capability Contracts is an opt-in layer for teams that want CI gates on what the system does, not just its code.
log · ask · switch · recap · status · bookmark · refresh
Mass-market, viral, zero-config. The whole loop above.
context · check · git-drift + inferno/ dir (capabilities.json, scenarios). CI gate via the infernoflow/action@v1 GitHub Action.
Branch model & sync
Captures on a feature branch travel with it via git. A teammate runs git checkout feature-auth; the JSONL is there, their MCP server boots, regenerates their rule files — their AI is warm-started on your findings, no message sent.
Personal preferences in global.jsonl follow you. Point at any OS-synced folder once — infernoflow sync set ~/Dropbox/… — and home → work → home just works. No infra to stand up; the OS does the sync.
Repository map
bin/infernoflow.mjs CLI router (~22 verbs) lib/ ├── commands/ log, ask, switch, bookmark, │ context, check, doctor, … ├── amp/io.mjs AMP read/write core ├── ruleFiles.mjs injection / refresh ├── learning/ profile, observe, adapt ├── git/ drift detection ├── ai/ optional provider router ├── adopters/ framework adopters ├── mcpRuntime.mjs MCP runtime stamp └── ui/ terminal output + prompts vscode-extension/ companion extension action/ GitHub Action v1 templates/ hooks, MCP server, CI dist/ esbuild output (committed)
node build.mjs — esbuild, single pass into dist/.postinstall. npm i -g only copies files.npm test runs the scripts/*-smoke.mjs chain end-to-end.Live sidebar (ranked by file), gotchas as Problems (yellow squigglies Copilot also sees), status-bar health score, keyboard-first logging (Ctrl+Alt+G/D/A/S/R). Registers amp_write/amp_read as VS Code Language Model Tools.
Security & privacy
No analytics, no error reporting, no install pings.
npm i -g infernoflow runs no code — it copies files.
Every default command runs entirely on your machine.
Reads/writes only inside .ai-memory/ and the three rule files at repo root.
Auto-content is wrapped in markers; your edits outside are untouched.
Entries matching secret patterns are refused at capture.
The optional infernoflow ai setup wires a provider (Anthropic / OpenAI / Google / Ollama) for a few enrichment commands — same trust model as using that provider directly. Off by default.
Design principles
Plain files, no service, no runtime dependencies. The moat is that it's boring infrastructure — set once, forget, like .gitignore.
An open protocol, not a format lock. Any AMP-Full client needs only the six amp_* tool names.
One install, everything wired — no separate setup steps, no manual rebuilds, no "now go install the other half".
infernoflow never runs your coding agent. It's the memory Cursor / Claude / Copilot read — that's the wedge, and it's deliberate.