Local-first LLM state branching & debugging. ForkMind treats AI context
windows like a Git repository: it captures every LLM call into a local
.forkmind/
directory, visualizes the conversation as a Directed Acyclic Graph (DAG), and lets you branch alternative prompts or model params from any point in the history — all on your machine, no cloud, no account.
Works with any OpenAI-compatible API, defaulting to free, open-source models via Ollama. Also supports Anthropic and any hosted free tier (Groq, OpenRouter, Together, vLLM, LM Studio).
Live demo: a conversation tree with a branch off the root, the node inspector (request/response, tokens, provenance), and the
Fork from heredialog.
Debugging agentic / tool-calling flows means re-running the same prompt with tiny tweaks over and over. ForkMind records each run as a node, so you can:
See the whole conversation tree, including tool calls and token usage.Branch from any historical turn — edit the prompt, swap the model, re-run.Compare outcomes visually instead of scrolling through terminal logs.
Everything is plain JSON on disk. No database. No telemetry.
npx forkmind init
npx forkmind start
npm install -g forkmind
forkmind start
No npm registry needed either — ForkMind runs straight from the git link, and the dashboard builds automatically on install:
npx github:medhovarsh/forkmind init
npx github:medhovarsh/forkmind start
git clone https://github.com/medhovarsh/forkmind
cd forkmind && npm install
ForkMind ships a Claude Code plugin (skill + /forkmind
command) so Claude knows when and how to drive it — same install flow as any marketplace plugin:
/plugin marketplace add Medhovarsh/forkmind
/plugin install forkmind
The plugin bundles:
— Claude reaches for ForkMind whenever you ask it to debug a prompt, compare models, branch from a past turn, or regression-test a call.forkmind
skill— start / branch / test / mcp on demand./forkmind
command— runs model/prompt comparisons in an isolated context and returns a compact verdict instead of dumping transcripts.forkmind-debugger
agentMCP server, auto-wired— agents query their own.forkmind/
history (recall attempts, trace lineage, self-correct) with zero manual config.
The CLI is still what runs the proxy + dashboard; the plugin is the glue that teaches Claude to use it.
ollama pull llama3
npx github:medhovarsh/forkmind init # create .forkmind/ in your project
npx github:medhovarsh/forkmind start # proxy on http://localhost:4500 + dashboard
open http://localhost:4500
npm i openai # the wrapper extends the official SDK
js
const { ForkMindOpenAI } = require('forkmind');
const client = new ForkMindOpenAI({
apiKey: 'ollama', // ignored by Ollama; required by SDK
upstream: 'http://localhost:11434', // free local open-source models
});
// Each call is recorded; sequential calls auto-chain into a conversation tree.
const res = await client.chat.completions.create({
model: 'llama3',
messages: [{ role: 'user', content: 'Explain backpropagation simply.' }],
});
Run the full example:
node examples/chain.js
The SDK wrapper is convenience, not a requirement. ForkMind's proxy speaks the
OpenAI-compatible wire protocol, so capture works from any language: set
your client's base URL to http://localhost:4500/v1
and you're recorded. Chain
turns into a tree by passing back the x-forkmind-node-id
from the previous
response as the next request's x-forkmind-parent
header (the JS wrapper just automates this).
from openai import OpenAI
client = OpenAI(base_url="http://localhost:4500/v1", api_key="ollama")
res = client.chat.completions.create(
model="llama3",
messages=[{"role": "user", "content": "Explain backpropagation simply."}],
extra_headers={"x-forkmind-upstream": "http://localhost:11434"},
)
curl http://localhost:4500/v1/chat/completions \
-H 'content-type: application/json' \
-H 'x-forkmind-upstream: http://localhost:11434' \
-d '{"model":"llama3","messages":[{"role":"user","content":"hi"}]}' -i
Go, Ruby, Rust, Java — same deal: base URL + the two headers. The dashboard, branching, MCP, and regression testing all work regardless of source language.
ForkMind ships thin adapters for the two biggest JS LLM ecosystems. Both route through the same proxy, so capture, branching, the dashboard, MCP, and regression all work unchanged — no model-class swap, no callbacks.
npm i @langchain/openai @langchain/core
js
const { ChatOpenAI } = require('@langchain/openai');
const { forkmind } = require('forkmind/langchain');
const fm = forkmind({ upstream: 'http://localhost:11434' }); // free local Ollama
const model = new ChatOpenAI({
apiKey: 'ollama',
model: 'llama3',
configuration: fm.configuration, // baseURL → proxy + chaining fetch
});
await model.invoke('Explain backpropagation simply.');
// sequential calls on `fm` auto-chain; fm.setParent(id) to branch from a node.
npm i ai @ai-sdk/openai
js
const { generateText } = require('ai');
const { forkmindOpenAI } = require('forkmind/vercel');
const openai = forkmindOpenAI({ upstream: 'http://localhost:11434' });
const { text } = await generateText({
model: openai('llama3'),
prompt: 'Explain backpropagation simply.',
});
// openai.setParent(id) / openai.resetParent() control the branch point.
Both honor FORKMIND_PROXY
(proxy base URL) and take an explicit baseURL
/
upstream
per instance.
ForkMind is provider-agnostic — it forwards your auth headers verbatim and lets you set the upstream per client. Anything OpenAI-compatible just works:
| Provider | upstream |
apiKey |
|---|---|---|
Ollama (local) |
http://localhost:11434 |
any string |
LM Studio (local) |
http://localhost:1234 |
any string |
Groq (free tier) |
https://api.groq.com/openai |
gsk_... |
OpenRouter |
https://openrouter.ai/api |
sk-or-... |
Together |
https://api.together.xyz |
your key |
OpenAI |
https://api.openai.com (default) |
sk-... |
new ForkMindOpenAI({ apiKey: process.env.GROQ_API_KEY,
upstream: 'https://api.groq.com/openai' });
You can also override per request with the x-forkmind-upstream
header if you call the proxy directly instead of via the SDK.
npm i @anthropic-ai/sdk
js
const { ForkMindAnthropic } = require('forkmind');
const client = new ForkMindAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
await client.messages.create({ model: 'claude-3-5-sonnet-latest', max_tokens: 512,
messages: [{ role: 'user', content: 'hi' }] });
your app ──▶ ForkMindOpenAI (baseURL = localhost:4500/v1)
│ injects x-forkmind-parent
▼
ForkMind proxy (Express, :4500)
│ forwards verbatim (your key, your upstream)
▼
provider (Ollama / Groq / OpenAI / ...)
│ response
▼
proxy reconstructs + saveNode() ──▶ .forkmind/nodes/<id>.json
│ returns x-forkmind-node-id
▼
wrapper chains it as the next call's parent
Deterministic node IDs.sha256(request + parentId)
→ first 12 hex chars. Same prompt under the same parent collapses to one node. The ID doesn't depend on the response, so it can be returned as a header even before a streamed body finishes.Streaming. Bytes pass through to your app untouched (real SSE); the proxy tees them, reconstructs the full message (textand fragmented tool-call arguments), and saves the node on stream end.Branching. Each node records its provider + upstream, so "Fork from here" in the dashboard replays the edited request to the same host, linked to the historical parent.
ForkMind ships an MCP server so an AI agent
can read its own .forkmind/
history mid-task and self-correct — recall what it already tried, see how it reached a state, or search past attempts.
forkmind mcp # stdio MCP server (or: forkmind-mcp)
One-line install via Smithery (configured in smithery.yaml) — run it from your project root so it sees your
.forkmind/
:
npx -y @smithery/cli install forkmind --client claude
…or register it manually with any MCP client (Claude Desktop / Claude Code / Cursor / Cline):
{
"mcpServers": {
"forkmind": {
"command": "npx",
"args": ["-y", "github:medhovarsh/forkmind", "mcp"]
}
}
}
Tools exposed:
| Tool | Purpose |
|---|---|
forkmind_recent |
|
| Newest captured turns (compact) | |
forkmind_get_node |
|
| Full request + response for one node | |
forkmind_lineage |
|
| Root→node path — the exact context that produced a state | |
forkmind_children |
|
| Sibling branches forking from a node | |
forkmind_search |
|
| Substring search across all requests/responses | |
forkmind_stats |
|
| Tree totals: nodes, roots, leaves, providers | |
forkmind_context_save |
|
| Offload context into an encrypted DAG capsule | |
forkmind_context_list |
|
| List saved capsules (title, digest, size, age) | |
forkmind_context_digest |
|
| Digest + segment map — cheap pre-restore probe | |
forkmind_context_restore |
|
| Full or per-segment restore, integrity-verified | |
forkmind_context_forget |
|
| Irreversible crypto-shred (requires id echo) | |
forkmind_context_replicas |
|
| Replica (RAID) health, optional sync | |
forkmind_context_stats |
|
| Aggregate stats: count, bytes, estimated tokens | |
forkmind_context_export |
|
| Portable passphrase-encrypted bundle | |
forkmind_context_import |
|
| Import + re-verify a bundle, re-wrap locally |
The server reads the .forkmind/
in its working directory — point the client's
cwd
at your project.
Most context managers treat a full window as a cache-eviction problem: truncate and lose it. ForkMind capsules invert that — persist first, verify, then compact. A capsule is an immutable, content-addressed DAG of context segments, AES-256-GCM encrypted on disk, restorable in full or one segment at a time.
echo '{"title":"auth debug","items":[{"role":"user","content":"..."}]}' \
| forkmind context save --digest "oauth loop root-caused; fix in token.js"
forkmind context list # all capsules, newest first
forkmind context show 9f3ac21b7e04 # decrypt + verify + print
forkmind context verify 9f3ac21b7e04 # DAG integrity: parents, acyclicity, hashes
forkmind context forget 9f3ac21b7e04 --confirm 9f3ac21b7e04 # crypto-shred
Same engine over HTTP (POST/GET/DELETE :4500/api/context…
) and via five MCP tools, so agents can archive their own context mid-task and pull it back later. The Claude Code plugin ships a ** forkmind-archivist** skill + subagent that teaches Claude the offload contract:
save → verify on disk → only then drop it from the window.
Guarantees:
Immutable & acyclic by construction— segment ids are hashes over content + parents (Git-style); a cycle would require a hash to contain itself.** No plaintext at rest**— per-capsule keys, wrapped by a master key storedoutside.forkmind/
(~/.forkmind-keys/
); an accidentally committed.forkmind/
leaks only ciphertext and structure.Digests are opt-in— the agent writes a ≤5-line retrieval summary, or omits it entirely for private capsules.** Forgetting is real**— delete destroys the key first (crypto-shredding), then tombstones the id so identical content can never resurrect it.** The model is never touched**— capsules operate on what the client sends; provider, weights, and KV cache are out of scope by design.
Mirror capsules to any number of extra filesystem targets (second disk, synced folder, network mount). Replicas hold ciphertext + manifests only — keys are never replicated. If the primary copy is lost or bit-rots, restore self-heals from the first replica that passes verification; healed copies get no trust shortcut (full integrity check still runs).
forkmind context replicas add D:\backup\forkmind # add target + sync
forkmind context replicas list # coverage per target
forkmind context replicas sync # catch up offline targets,
Forgetting reaches every copy: reachable replicas are shredded immediately;
a replica that was offline gets its stale ciphertext removed on the next
sync
(tombstone propagation) — and it was unreadable anyway, since the capsule key died at forget time. Tombstones also make heal refuse to resurrect anything forgotten.
Move a capsule to another machine or project — a laptop that doesn't share
this project's ~/.forkmind-keys/
master key, a teammate, cold storage:
forkmind context export 9f3ac21b7e04 --passphrase "correct horse battery staple" --out capsule.json
forkmind context import capsule.json --passphrase "correct horse battery staple"
The bundle carries its own scrypt-derived key material (N=32768, deliberately slow to resist offline brute force of a weak passphrase) — it never depends on the source machine's master key, and the passphrase is never written into the bundle itself. On import, every segment is independently re-verified (recomputed id, recomputed hash, resolved parents, acyclic DFS) before anything touches disk — the bundle is never trusted blindly, only proven. Import is idempotent and honors tombstones, same as a fresh save.
The two halves connect: any conversation the proxy captured can be archived
into a capsule in one move — no manual JSON assembly — and restored later as
a provider-ready messages[]
array, ready to splice into the next request:
forkmind context save --from-node a1b2c3d4e5f6 --digest "auth debug, resolved"
forkmind context show 9f3ac21b7e04 --messages
Same via MCP: forkmind_context_save { fromNodeId }
and
forkmind_context_restore { asMessages: true }
— an agent can archive its own
captured history mid-task and splice it back whenever needed. Capsules keep
sourceNodeIds
links back into the turn DAG.
forkmind context save
and forkmind context stats
report an estimated
token count freed from your context window (~4 bytes/token
, the standard rough heuristic) — a concrete number for how much a capsule actually saved.
Tweaking a system prompt or swapping a model can silently degrade results. ForkMind lets you pin a known-good captured node as a baseline, then re-run its exact request later and check the new output for drift.
forkmind regression pin a1b2c3d4e5f6 \
--name octopus-fact \
--contains "hearts" \
--regex "blue|copper" \
--min-similarity 0.5
forkmind regression list
forkmind regression remove octopus-fact
forkmind regression run # keyless local (Ollama)
forkmind regression run --key $GROQ_API_KEY --upstream https://api.groq.com/openai
Each case checks the replayed output against:
— substrings that must appearcontains
— substrings that must NOT appearnot-contains
— patterns that must matchregex
— Jaccard word-overlap vs the baseline (drift guard; defaults tomin-similarity
0.3
so a wildly different answer fails even without explicit assertions). LLM output is non-deterministic, so prefer assertions over exact match.
Cases are JSON in .forkmind/regressions/
— commit them to share baselines and gate prompt changes in CI.
No paid API required— defaults to free local models via Ollama.** No database**— every turn is a plain JSON file under.forkmind/
.No account, no telemetry— nothing leaves your machine except the LLM call you were already making (relayed verbatim to the provider you choose).
.forkmind/
├── nodes/
│ ├── a1b2c3d4e5f6.json # one node per turn
│ └── ...
├── contexts/ # encrypted context capsules
│ └── 9f3ac21b7e04/
│ ├── manifest.json # public: DAG shape, hashes, opt-in digest
│ └── seg-<id>.enc # AES-256-GCM ciphertext per segment
├── tombstones.json # forgotten capsule ids (never resurrected)
└── manifest.json # version + root node ids
Node schema:
{
"id": "a1b2c3d4e5f6",
"parentId": null, // null = root
"timestamp": "2026-01-01T00:00:00.000Z",
"request": { /* the exact request body */ },
"response": { /* full or stream-reconstructed response */ },
"meta": { "provider": "openai", "upstream": "http://localhost:11434", "stream": true },
"children": ["..."] // child node ids
}
| Command | Does |
|---|---|
forkmind init |
|
Create .forkmind/ in the current directory |
|
forkmind start |
|
Start the proxy (:4500 ) + serve the dashboard if built |
|
forkmind context save/list/show/verify/forget |
|
| Encrypted context capsules (see above) |
Env vars: FORKMIND_PORT
, FORKMIND_HOST
(default 127.0.0.1
— loopback
only; set 0.0.0.0
to expose on the LAN at your own risk),
FORKMIND_OPENAI_UPSTREAM
, FORKMIND_ANTHROPIC_UPSTREAM
, FORKMIND_PROXY
(SDK target base URL), FORKMIND_KEY_DIR
(capsule master-key location,
default ~/.forkmind-keys
).
npm install # installs proxy + dashboard (npm workspaces)
npm test # jest: hashing, storage, stream reconstruction, API
npm run dashboard:dev # vite dev server on :5173, proxies API to :4500
npm run dashboard:build
npm run lint
Publishing is tag-driven via .github/workflows/release.yml
(needs an
NPM_TOKEN
repo secret with publish rights):
npm version patch # bumps package.json + tags
git push --follow-tags # tag push → CI lints, tests, builds dashboard, publishes
prepack
rebuilds dashboard/dist
so the tarball always ships the UI.
See CONTRIBUTING.md.
- CLI + deterministic storage engine
- Provider-agnostic proxy (OpenAI-compatible + Anthropic) with streaming
- Drop-in SDK wrappers with auto-chaining
- React Flow dashboard + branch execution
- MCP integration — let agents query their own
.forkmind/
history - Automated regression: pin "good" branches, re-run on prompt edits
- Context capsules — offload context as an encrypted, immutable DAG; restore in full or per segment; crypto-shred to forget
- RAID — Redundant Array of Independent DAGs: replicate capsules across filesystem targets with self-healing restore and tombstone propagation
- Capsule export/import — portable, passphrase-encrypted bundles to move context between machines and projects, independently re-verified on import
- Dashboard capsule panel — browse capsules, inspect the DAG segment map, and run integrity verification from the UI (read-only by design)