Infernoflow

🔥 infernoflow

Every new AI session starts cold — the gotchas you found, the decisions you made, don't survive. infernoflow makes them stick.

Persistent memory for AI coding sessions. Captures the gotchas, decisions and dead ends your code can't tell an agent — and replays them into your next Cursor / Claude Code / Copilot chat so the same wrong turn never happens twice.

[npm version] [npm downloads] [zero runtime dependencies] [VS Code Marketplace] [License: MIT] [infernoflow MCP server on Glama]

You spent 90 minutes yesterday teaching Claude that your auth API returns 200 even on errors — check the response body, not the status code. Today you ask the same kind of question and watch it write if (response.ok) { return data } all over again. The AI didn't get worse overnight. It just doesn't have memory.

infernoflow is a local-first CLI + VS Code extension + open protocol (AMP) that gives your AI persistent context across sessions. No SaaS. JSONL on disk. Three rule files your IDE already reads.

Built-in assistant memory remembers you. infernoflow remembers the codebase: the memory lives in your repo under .ai-memory/, travels through git to your teammates, and works the same in Claude Code, Cursor and Copilot.

[Demo: Dana logs a gotcha and bookmarks where she stopped. Omer pulls, runs infernoflow resume, then asks Claude Code "where were we?" and it picks up where Dana left off.]

What's new in 0.50

• The MCP server tells the agent how to use the memory. Clients that show MCP server instructions, such as Claude Code, now get the memory protocol when they connect: check where you stopped, search before changing a file, save decisions, gotchas and failed attempts without being asked. It works even where no hook or rule file loads it.

What's new in 0.49

• Unsaved decisions come back. If a Claude Code session ends with a decision or finding you stated but nobody saved, the next session starts with a one-time reminder to offer saving it (the quote stays on your machine).
• setup shows what is really installed — every part, installed, skipped with the reason, or missing with the command that fixes it.
• setup runs init with the CLI you installed, never npx through a shell.

What's new in 0.48

• Codex CLI. setup registers the MCP server in .codex/config.toml (no machine paths, safe to commit) and creates AGENTS.md with the memory block, on machines with Codex.
• Pre-commit note. When a commit touches a file that memory has a gotcha, failed attempt or decision about, git commit shows it first. Never blocks.
• Safer uninstall. It removes only infernoflow's block from your rule files; it used to delete CLAUDE.md whole.

What's new in 0.47

• Committed configs stay clean across the team. .vscode/mcp.json and .cursor/mcp.json no longer hold your machine's paths (infernoflow mcp in ${workspaceFolder}), and the rule files no longer list recent commits or personal memory — so a teammate's pull doesn't leave changed files. Optional AGENTS.md support.
• Save reminders from what you type (Claude Code): "remember this", "we decided…", "turns out…" — in English or Hebrew — remind the agent to save it in its own words. Hebrew frustration phrases are logged too.

What's new in 0.46

• Memory maintenance hints (0.46.5): status, recap and the session start tell you when memory has duplicates, noise or entries about files that changed since, and name the command to fix it. Set "maintenance": "auto" in .ai-memory/amp.json to tidy up once a day, or "off". Also: every command has its own --help that never runs the command.
• Fresh memory every Claude Code session — a SessionStart hook injects current memory (framed as information to verify, not instructions); CLAUDE.md no longer carries a copy that goes stale.
• infernoflow resume — "where were we?" in one call. Claude Code also leaves an automatic local resume point when a session ends.
• Stale and resolved entries — entries about a file that changed since are marked may be stale; infernoflow resolve <id> retires one from AI context.
• Review what arrives through git (0.46.1) — memory added by teammates is listed until you review it, and the GitHub Action shows memory changes in each PR.
• Safer by default — only read-only MCP tools are pre-approved; the memory-keeper agent is limited to single infernoflow commands; secrets are redacted; MCP is registered per project.
• infernoflow doctor --e2e (0.46.3) — an end-to-end self-test in a throw-away sandbox: CLI, the MCP server with every tool called, the prompt and session hooks, git drift, attribution. Also: prompt hooks ignore agent/tool text, memory-mode projects aren't offered contract tools, git drift reports git failures, and every entry names who wrote it.

Full list: CHANGELOG.md.

Session bookmarks

Drop a named resume point mid-session. When the context window fills up or you're about to make a risky change, one command captures the current session's transcript and stores it as a jumpable checkpoint:

infernoflow bookmark "before the SP refactor"

Or just say it in chat — the Cursor beforeSubmitPrompt hook catches phrases like "bookmark this" / "mark this point" / "save this checkpoint" and drops the bookmark itself, no AI cooperation required. Or let the AI do it via the amp_bookmark MCP tool when it notices the session is getting long.

No --note? infernoflow reads Claude Code's own on-disk transcript (~/.claude/projects/…/*.jsonl), distills the last 40 turns to markdown, and stores it as the bookmark's context. Fully deterministic — no model call. Recall any time:

infernoflow bookmark list                # ● has context, ○ marker onlyinfernoflow bookmark show "SP refactor"  # jump back — see the whole snapshot

Bookmarks are never auto-pruned, and they surface in infernoflow switch under a ## 🔖 Bookmarks — Resume Points section so the next session opens right where work paused.

🆕 Proactive capture — a Claude skill + a memory-keeper agent

init now installs two things into .claude/ so the loop runs itself on Claude Code:

• infernoflow-memory skill (.claude/skills/) — teaches the agent to start warm (resume), then proactively log real gotchas, decisions-with-a-because, dead ends, and durable preferences, and drop a bookmark at stopping points or when you say "bookmark this". Capture is balanced — it skips routine steps, anything obvious from the code, secrets, and duplicates.
• memory-keeper subagent (.claude/agents/) — a specialist you can delegate to. It sweeps the session, dedupes against what's already stored, logs what's worth keeping, drops bookmarks, and reports back. It never edits code or logs secrets, and a guard limits its shell to single infernoflow read/log commands (blocked if the guard can't run).

Both are installed automatically by infernoflow init (fresh and on re-run of an existing project) and ship in the package — nothing to set up by hand.

The loop

Every new AI session today starts cold. The agent re-reads your code, re-derives the obvious, and re-makes the same wrong move someone else made yesterday. infernoflow closes that loop in four stages:

1. Capture — while you and the agent work, moments worth saving get logged automatically: a gotcha hit, a decision made, an attempted fix that failed, a pattern noticed, a resume point marked. The AI writes them via the amp_write MCP tool. A protocol block injected into the rule files teaches it exactly when. Prompt hooks (Claude Code UserPromptSubmit, Cursor beforeSubmitPrompt) backstop the AI by scanning the text you typed — subagent hand-backs, system reminders, fenced or indented code, quotes and stack traces are skipped — for trouble signals (not working, still broken, same error; !! / retry only in short prompts) and writing the entry deterministically when the AI doesn't (English and Hebrew). In Claude Code the hook also notices when you ask the agent to remember something, state a decision or describe a finding, and reminds the agent to save it in its own words — it stores nothing itself for those. If a session ends with one of those still unsaved, the next session starts with a one-time reminder to offer saving it. The Cursor hook also turns "bookmark this" into a bookmark.
2. Link — each captured moment becomes a structured AMP entry (gotcha | decision | attempt | note | detection | pattern | bookmark) with timestamp, file:line, tags, and a stable AMP id.
3. Persist — entries land in .ai-memory/branches/<branch>.jsonl (git-tracked, travels with your branch — teammates inherit it) plus .ai-memory/global.jsonl (personal preferences, gitignored, synced across your machines via any OS-synced folder).
4. Restore — when a new session starts, the agent reads CLAUDE.md / .cursorrules / copilot-instructions.md at boot. The most relevant entries are already there. Warm start; no cold derivation.

And at the last moment before a repeat: when a commit touches a file that memory has a gotcha, failed attempt or decision about, the git pre-commit note prints those entries — to you or to the agent running git commit. It never blocks the commit. (setup / init install it in .git/hooks; turn it off with "preCommit": "off" in .ai-memory/amp.json.)

No service to log into. No SaaS. JSONL on disk, an MCP server, and three rule files your IDE already reads.

Install

npm install -g infernoflowinfernoflow init --yes

Zero runtime dependencies. Works on Node ≥ 18 — macOS, Linux, Windows.

init --yes does the whole setup: creates .ai-memory/, writes rule files for every supported IDE, wires the MCP server for Cursor / VS Code Copilot / Claude Code in one shot, installs the infernoflow-memory skill + memory-keeper agent into .claude/, applies the clean-tree git policy, and drops a visible demo entry so you can confirm the loop is alive with:

infernoflow status

The 5-command core + 4

These cover 95% of usage:

Any command takes --project <dir> to work on another project's memory (multi-folder workspaces, hooks, agents).

In practice you barely run any of these — the MCP-aware AI does it for you. The CLI is for grep-style introspection.

infernoflow commands shows the full list (~23 commands, grouped by purpose).

Works with GitHub Copilot Chat — via LMT + MCP

Copilot Chat has supported MCP servers since VS Code 1.102 (GA July 2025), so any MCP-based memory tool can plug in. infernoflow ships two transports side by side so Copilot picks up the same six amp_* tools whichever path is available:

• VS Code Language Model Tools (LMT). The infernoflow VS Code extension registers amp_write and amp_read as native LMT tools. No per-project config, no MCP client setup — install the extension and Copilot's tool picker shows 🔥 amp_write. Call by hand with #amp_write / #amp_read in the chat box.
• MCP server. infernoflow init wires the MCP server into .vscode/mcp.json too, so Copilot's MCP client can call the same tools if you prefer that route (or want them available to agent mode).

Cursor, Claude Code, and any MCP-capable client use the same MCP server. One product, one disk file, multiple transports — pick whichever fits your setup; both write to the same .ai-memory/.

Keeping it lean: token budget + rotation

The injected memory block is paid for on every AI turn (and twice when a tool loads both CLAUDE.md and copilot-instructions.md). infernoflow ships lean defaults — 4 entries, no commit list (0.46.6: a commit list made the committed rule files change after every commit), 200-char truncation, and a compact ~3-line protocol (the full trigger table is redundant with the amp_* tool descriptions, so it's off by default: ~430 tokens/file/turn saved). Tune further in .ai-memory/amp.json:

"config": {  "injection": {    "maxEntries": 4,                          // memory entries injected    "maxCommits": 0,                          // git commits injected (0 = none, the default)    "maxEntryChars": 200,                     // per-entry truncation    "targets": ["CLAUDE.md", ".cursorrules"], // drop a file from the list and its stale block is stripped automatically; add "AGENTS.md" to write it there (an existing AGENTS.md is used by default)    "protocolStyle": "compact"                // "compact" (default) · "full" (restore the trigger table) · "off"  },  "rotation": {    "archiveAfterDays": 30,    "archivableTypes": ["note", "attempt", "detection"],    "auto": false                             // true → silent prune on every `log`  },  "maintenance": "suggest"                    // "suggest" (default) · "auto" · "off"}

Or write the same values via CLI flags:

infernoflow setup   --max-memory 3 --max-commits 0 --max-entry-chars 200 --protocol-style compactinfernoflow refresh --targets CLAUDE.md,.cursorrules # only these get the block; the rest are strippedinfernoflow refresh --targets auto                   # canonical file for the IDE you're in (kills Copilot's double-load)infernoflow prune --apply --max-age-days 14          # one-off cleanup

Rotation archives stale note / attempt / detection entries to .ai-memory/archive/sessions-YYYY-MM.jsonl — invisible to the merged read (so the AI, sidebar, ask, and refresh stop surfacing them) but still on disk if you want them back. gotcha, decision, pattern, and bookmark entries are never auto-pruned — that's the knowledge you logged infernoflow FOR.

Maintenance hints (0.46.5): when memory collects noise (duplicates, old commit notes, machine text), entries about files that changed since, or a pile of old notes, status, recap and the session-start context say so and name the command (curate --apply, resume, prune --apply). The session-start hint shows at most once a day and tells the AI to ask before running anything. "auto" does the safe part itself once a day (noise is archived then removed, old notes go to the archive); entries about changed files are still only suggested, because a person decides whether they're outdated. Thresholds are adjustable: "maintenance": { "mode": "suggest", "thresholds": { "curate": 3, "stale": 3, "prune": 20 } }.

Two-tier bodies: any entry can carry a rich detail — stored in a single .ai-memory/details.jsonl (consolidated in 0.44.18; older per-entry details/<id>.md sidecars auto-migrate on the next write), loaded on demand via readDetail(), and never injected into rule files. The lean index stays lean; you pay for the body only when you open it. log --detail, --detail-file, MCP amp_write detail, and the new amp_bookmark tool all feed it.

Branch-aware memory + cross-machine sync

Your teammate takes your branch — they inherit your memory.

.ai-memory/├── branches/│   ├── main.jsonl              ← project-wide truths (git-tracked)│   └── feature-auth.jsonl      ← your current branch's work (git-tracked)├── details.jsonl               ← long-form entry bodies (git-tracked, loaded on demand)├── details.local.jsonl         ← bookmark transcript snapshots (gitignored, this machine only)├── global.jsonl                ← your personal preferences (gitignored)└── sessions.jsonl              ← everything this machine wrote (gitignored mirror)

• Captures on a feature branch travel with that branch via git. When a teammate runs git checkout feature-auth, the JSONL is there. Their MCP server boots, reads it, regenerates their rule files — their AI is warm-started on your findings without you sending a message.
• You see what arrives. Entries that reach your machine through git and that you haven't reviewed are listed by infernoflow resume (and in Claude Code's session-start context); infernoflow recap shows them and marks them reviewed. Tracked locally per machine, from the entry's content — not from the author it claims. Retire a wrong one with infernoflow resolve <id>.
• Review memory in pull requests. The GitHub Action (action/) comments on each PR with the memory entries it adds, edits or deletes, so they are reviewed like code before they reach everyone's AI.
• Personal preferences travel between your own machines. Point at any OS-synced folder once:
  infernoflow sync set ~/Dropbox/infernoflow-memory

  Home → work → home. No infra to stand up; the OS does the sync.
• merge=union on branch JSONLs means concurrent commits from different machines merge cleanly — no manual conflict resolution.
• Branch switching never blocked. Rule files refresh only at MCP server boot or via explicit infernoflow refresh, not on every entry — your working tree stays clean while you log.

Cross-IDE — same memory, every tool

The MCP server is wired by infernoflow setup / init into each tool's config file. No per-tool setup. The committed configs (.vscode/mcp.json, .cursor/mcp.json, .codex/config.toml) only name the command (infernoflow mcp), never a path on your machine, so teammates share them as they are.

MCP tools (for AI agents)

When the MCP server is wired, your AI agent can call these directly in chat:

Entries are stamped with who wrote them: the MCP client that called the tool (Claude, Cursor, Copilot, Windsurf…), claude for CLI calls from Claude Code, memory-keeper / hook for the agent and the prompt hooks, human for you. Set INFERNOFLOW_AGENT to override the automatic detection. Like the author, this is what the writer claims — useful for triage, not proof.

The amp_* tools follow the AMP MCP spec §7.3 — vendor-neutral. Any AMP-Full client only needs to know those six names. The same six are also available as CLI aliases (infernoflow amp read | write | search | bookmark | handoff | health) so the CLI and MCP surfaces match name-for-name.

Every memory line injected into the rule files is prefixed with 🔥 so the AI (and you) can tell at a glance that a line came from infernoflow even when it's quoted out of the managed block. When the AI uses one, the protocol tells it to briefly cite the source — e.g. 🔥 (from infernoflow memory) gotcha at src/api.js:42: API returns 202 not 200.

What it has caught (real dogfood)

infernoflow was developed by building a multi-tenant kanban (infernotest_01) and capturing what it surfaced. A sample of real entries from that dogfood:

• gotcha (vite.config.ts): "Vite proxy with changeOrigin: true rewrites the Host header — server-side URL construction produces URLs pointing at the BACKEND port. Build user-facing URLs client-side via window.location.origin."
• gotcha (server/prisma/schema.prisma): "Prisma 6 query_engine.dll.node is locked while tsx watch is running; prisma migrate dev fails with EPERM on rename. Stop the dev server before migrating."
• gotcha (server/src/routes/members.ts): "Invite accept must NOT burn the token when the caller is already a member of the workspace — return early with the existing membership before marking acceptedAt."
• pattern (server/src/routes/columns.ts): "Position assignment for ordered children: next position = max(existing) + 1024. The 1024 step leaves room for ~10 inserts between two siblings without renumbering."
• pattern (server/src/access.ts): "Cross-entity auth helpers do where: { memberships: { where: { userId } } } via Prisma nested-select — one DB hop per assertion. Return 404 not 403 when not a member to avoid leaking existence."
• decision (server/src/auth.ts): "Opaque session tokens in a Session table (not JWTs) — chosen so we can revoke per-session (deleteMany on Session). bcryptjs over native bcrypt to avoid platform-specific binaries."

These are the things you'd otherwise forget by next Tuesday and re-derive at 11pm on a Friday. They live in .ai-memory/branches/*.jsonl forever.

VS Code extension

The companion extension is the visual surface over your memory:

• Live sidebar — ranked-by-relevance gotchas / decisions / attempts for whatever file you're editing.
• Gotchas as Problems — logged with a file:line? They appear as yellow squigglies in the editor and rows in the Problems panel, right next to your TypeScript errors. Both you and Copilot see the warning before making the same mistake again.
• Status bar health score — always visible: 🔥 B 65 · ⚠3 · ✓2 · ❌1 · 📋 Switch. Click Switch to copy the handoff.
• Copilot Chat integration — #amp_write / #amp_read in the chat box; Copilot picks them up via VS Code Language Model Tools registered by the extension (works even without an MCP client configured).
• Keyboard-first logging — Ctrl+Alt+G (gotcha) / Ctrl+Alt+D (decision) / Ctrl+Alt+A (ask) / Ctrl+Alt+S (switch) / Ctrl+Alt+R (recap). Right-click in the editor to log a gotcha for the current line.

ext install infernoflow.infernoflow

Or in the Marketplace: infernoflow.infernoflow. Activates on any project with .ai-memory/ (or legacy inferno/).

The extension is window only in v0.7.9+ — the CLI is the single canonical writer of rule files. No race between extension and CLI; the extension watches .ai-memory/**/*.jsonl and renders.

Troubleshooting

• I upgraded infernoflow but amp_write entries still look wrong. Your IDE's MCP server is loaded into memory at session start and doesn't reload from disk. Quit and reopen Cursor / Claude Code / VS Code. infernoflow doctor will flag this with a "MCP runtime v… but CLI v…" warning.
• infernoflow not found. Use npx infernoflow until the global install resolves on your PATH.
• PowerShell script execution blocked. Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass.
• Box-drawing chars look broken. Force UTF-8 first: [Console]::OutputEncoding = [System.Text.Encoding]::UTF8. Should auto-fall-back to ASCII on legacy PowerShell. If not, open an issue.
• infernoflow doctor — full diagnostic if anything looks wrong. Includes the MCP runtime stamp check + AI provider detection + git hooks status.
• infernoflow doctor --e2e — if memory isn't being captured or a tool fails, this runs the whole chain in a temporary sandbox (your project and settings aren't touched): log → ask → forget, the MCP server with every tool called, the prompt and session hooks with sample input, git drift, and attribution. Paste its output into an issue.
• infernoflow check says memory mode. That's expected after a plain init: capability contracts are optional. Enable them with infernoflow init --mode full --adopt. In CI use infernoflow check --strict, which fails when the contract is missing.

Why this matters

Code changes daily. What the system actually does under all those edits — the invariants, the constraints, the things that bit you last week — code can't tell you. infernoflow keeps that current and feeds it to the agent so the agent stops re-deriving from scratch.

That's the whole product. No vendor lock-in (it's JSONL on disk). No SaaS. One CLI, one VS Code extension, one open protocol, three rule files your IDE was reading anyway.

Security & privacy

Local-first by design:

• ✅ Telemetry is opt-in and off by default. After a few runs in an interactive terminal infernoflow asks once; nothing is sent unless you answer yes. It never sends code, file paths or memory content. Check or change it with infernoflow telemetry status.
• 🚫 No postinstall script. npm install -g infernoflow runs no code — it only copies files.
• 🚫 No network calls in any default command path (with telemetry off, which is the default).
• 🚫 No auto-updates of the package, no background processes, no cloud sync.
• ✅ MCP is registered per project. Claude Code gets the project's own .mcp.json (gitignored — it holds this machine's paths); Cursor and VS Code get .cursor/mcp.json / .vscode/mcp.json with no machine paths (infernoflow mcp in ${workspaceFolder}), so they are safe to commit and stay unchanged when teammates run setup. All of them run the server from the installed package (infernoflow mcp), not a copy inside the repo.
• ⚠️ Writes outside the project: Claude Desktop has no per-project config, so setup adds one entry per project there (infernoflow-<repo>). Pre-0.45 versions left a single infernoflow entry in ~/.claude.json / the Desktop config that pinned every project to one repo; it is removed automatically (backup in ~/.infernoflow/backups/). Personal settings and API keys live in ~/.infernoflow/.
• ✅ Auto-injected content is wrapped in markers (<!-- infernoflow:start --> / <!-- infernoflow:end -->) — your manual edits outside the block are never touched.
• ✅ Secrets are redacted before anything is written — GitHub/npm/OpenAI/Anthropic/AWS/Google/Slack/Stripe tokens, JWTs, private keys, URL credentials and password=-style values become [REDACTED:<kind>]. Memory files are still plain text committed with your repo, so treat them like code: review .ai-memory/ diffs.
• ✅ Bookmark transcript snapshots stay on your machine (.ai-memory/details.local.jsonl, gitignored). Only context you write explicitly (--note, detail) is shared with the team.
• ✅ API keys never live in the project — environment variables are used as-is; pasted keys go to ~/.infernoflow/ai-credentials.json (owner-only).
• ✅ No shell is used to run commands from the MCP server or the prompt hooks (since 0.44.20), and MCP tool arguments are validated against their schema.
• ✅ Only read-only tools are pre-approved in Claude Code (permissions.allow in .claude/settings.json). Tools that write memory ask for your permission like any other tool, so text the AI reads can't silently write to shared memory.
• ✅ Memory is data, not instructions. Injected memory is framed that way, each entry records its author and the tool that wrote it, entries about a changed file are marked may be stale, and memory that arrived through git is listed until you review it (resume / recap).
• ✅ The frustration hook keeps only a 60-character prefix of the prompt that triggered it, and skips agent hand-backs, system reminders, code, quotes and stack traces in it.

The optional infernoflow ai setup command wires an AI provider (Anthropic / OpenAI / Google / Ollama) for a few enrichment commands — same trust model as using that provider directly. Off by default.

Full policy: SECURITY.md. Vulnerability reports: [email protected] or GitHub Security Advisory.

Community

• 💬 GitHub Discussions — Q&A, ideas, show and tell. First stop for questions.
• 🐛 Issues — bugs only. Feature requests go in Discussions → Ideas.
• 🔒 Security Advisories — private disclosure for vulnerabilities.

License

MIT — see LICENSE.

Links

• GitHub · Discussions · npm · VS Code Marketplace · infernoflow.dev
• AMP protocol spec — vendor-neutral memory format
• [Dogfood: what infernoflow caught