Caching

You run the same code audit every morning. Most of the files haven't changed since yesterday — the auth module is the same, the config loader is the same, only one PR touched the billing service. And yet every morning you pay to re-analyze all of it.

taskflow's caching exists to fix exactly this. It has two layers that work at different time scales, and together they make sure you only pay for work whose inputs actually changed.

The two layers at a glance

Within-run resume is free

The moment you run a flow, within-run resume is already on. You don't configure anything.

Here's what it does: if a phase's inputHash matches a prior done phase from the same run, the phase is skipped and its prior output is reused. The phase is marked cacheHit: "run-only", and its prior usage is preserved so the run summary can tell you what the reuse would otherwise have cost.

This is what makes resume cheap. Abort a run mid-flight, fix a typo, and re-run — only the phases whose inputs actually changed re-execute. Everything else is a hash comparison.

{
  "name": "audit",
  "phases": [
    {
      "id": "scan",
      "type": "agent",
      "task": "List the changed files under src/."
    }
  ]
}

That's it. No cache field, no flags. The phase is already content-addressed and resumable within the run.

Cross-run memoization

Within-run resume only looks inside one run. If you run the same flow tomorrow, it starts from scratch — even if nothing changed.

Cross-run memoization fixes that. Set cache.scope to "cross-run" and the phase's result is stored on disk under .pi/taskflows/cache/. The next run — tomorrow, next week, in a different session — checks the same inputHash against that store. A hit means zero tokens, zero cost.

Here's the 80% case: a phase that should reuse its result as long as the git commit hasn't moved.

{
  "id": "analyze-auth",
  "type": "agent",
  "task": "Summarize how auth works in src/auth/.",
  "context": ["src/auth/**/*.ts"],
  "cache": {
    "scope": "cross-run",
    "fingerprint": ["git:HEAD"]
  }
}

Run this once and it costs whatever the agent costs. Run it again at the same commit and it costs nothing. Push a new commit and the git:HEAD fingerprint changes, the key changes, and the phase re-executes — which is exactly what you want.

On a cross-run hit, the full phase state is restored (preserving gate verdicts, approval state, reads, loop/tournament metadata, warnings), usage is zeroed, and the phase is marked cacheHit: "cross-run".

When should you reach for cross-run?

The cache field

Three optional fields. An empty cache: {} is valid and equivalent to the default.

The three scopes

TTL: when stale results are dangerous

Sometimes "the inputs haven't changed" isn't enough — the result itself goes stale. A security summary written two weeks ago may not reflect a vulnerability introduced yesterday, even if the task text and context files are byte-identical.

ttl puts a time bound on a cross-run hit:

{
  "id": "security-summary",
  "type": "agent",
  "task": "Summarize known security risks in src/.",
  "cache": {
    "scope": "cross-run",
    "ttl": "6h",
    "fingerprint": ["git:HEAD"]
  }
}

This phase reuses its result for up to six hours after it was first computed. After that, the entry is treated as a miss and the phase re-executes.

The grammar is a number followed by an optional unit:

A malformed or non-positive ttl is a hard validation error. Run /tf verify to catch it before any tokens are spent.

Fingerprints: telling the cache about the world

Without a fingerprint, a cross-run phase only invalidates when its declared inputs change — the task text, the context files, the args, the upstream outputs. That's usually enough. But sometimes the thing that should invalidate the cache lives outside the flow definition: the current git commit, the contents of a config file, the value of an environment variable.

A fingerprint folds those external signals into the cache key. Each entry is a string <prefix><value>. The runtime resolves each entry to a deterministic string, hashes the concatenation, and folds the digest into the key.

The five prefixes

glob: vs glob!:

"fingerprint": ["glob:src/**/*.ts"]

"fingerprint": ["glob!:src/**/*.ts"]

A realistic fingerprint

{
  "id": "lint-summary",
  "type": "agent",
  "task": "Summarize the lint findings across the repo.",
  "cache": {
    "scope": "cross-run",
    "fingerprint": ["git:HEAD", "glob:src/**/*.ts", "glob!:package.json"]
  }
}

This misses when the commit moves, when any TypeScript file is modified, or when package.json's content changes — three independent signals, all folded into one digest.

Opt the whole flow in: incremental: true

If most of your phases should be cross-run cached, set incremental: true at the flow level. It defaults every phase's cache scope to "cross-run".

{
  "name": "code-review",
  "incremental": true,
  "phases": [
    {
      "id": "discover",
      "type": "agent",
      "task": "List the changed files.",
      "cache": { "fingerprint": ["git:HEAD"] }
    },
    {
      "id": "review",
      "type": "agent",
      "task": "Review {steps.discover.output}.",
      "dependsOn": ["discover"]
    }
  ]
}

Now re-running the flow reuses unchanged phases across runs and sessions. The precedence rules are simple:

Edge cases worth knowing

idempotent: false disables all caching

A phase that performs an irreversible side effect (a deploy, a webhook POST, a DB write) must never be replayed from cache. Set idempotent: false and the effective scope becomes "off" — one assignment covers every cache path, including the map per-item path.

Blocked phase types

These phase types cannot use cache.scope: "cross-run":

This is enforced twice: schema validation rejects it at /tf verify (zero cost), and the runtime downgrades it to "run-only" as defense in depth.

When the flow definition can't be hashed

If the flow-definition hash fails to compute (flowDefHash === "failed"), all cross-run phases are downgraded to "run-only" for that run. Without the flow hash, the key would degrade to flow-name-only and reopen cross-flow collisions. Run /tf verify to diagnose why the hash failed.

How the cache key is computed

The full identity for a cross-run phase is a SHA-256, truncated to 16 hex characters:

key = sha256(
  "flow:" + flowName,
  "v3:phasefp:" + (phaseFp ?? flowDefHash),   // per-phase structural sub-fingerprint
  phaseId,
  agentName,
  model,
  resolvedTaskText,          // after interpolation
  "think:" + thinking,
  "tools:" + JSON(tools),
  "ctx:" + preRead,          // resolved context file contents
  fingerprintDigest          // only when scope === "cross-run"
).slice(0, 16)

A few things worth noting:

• Interpolation happens before hashing. A map phase that fans out over {steps.discover.json} gets a different key per item when discover's output changes — no fingerprint needed.
• context file contents are part of the identity. Editing a context file always invalidates the phase, independent of whether the task text mentions it.
• The fingerprint digest is only resolved for cross-run phases. For run-only it's an empty string — within-run resume already captures declared-input changes.
• Editing phase B invalidates only B and its transitive dependents, not the whole flow. That's the per-phase structural sub-fingerprint (v3:phasefp:).

Per-phase-type additions

Each phase type folds a little more into the key:

Backward compatibility: four keys, one write

cacheKeys() produces four keys for every phase. Only key is written; the others are read-only fallbacks so an upgrade never produces a miss-storm:

A hit on any tier is restored as a cache hit. taskflow does not write-through, so the cache size stays stable and legacy entries age out naturally.

Where the cache lives

The cross-run cache is a directory of .json files under .pi/taskflows/cache/ in your project — the nearest .pi directory walking up from cwd, never ~/.pi/.

Eviction is opportunistic: triggered on each write. Entries older than the 90-day backstop are dropped; if the live count exceeds 1000, the oldest go first.

Debugging

Reading the reuse summary

Every run result carries a reuse summary:

Each phase state carries a cacheHit marker: "run-only", "cross-run", or undefined (freshly executed).

Forcing a re-run

A forceRerun seed bypasses both the within-run prior and the cross-run store for a single phase. Downstream phases are not forced — they re-evaluate naturally: if the seed's new output changed their inputHash, they miss and re-run; otherwise they hit.

Inspecting the cache

# Where is the cache?
ls .pi/taskflows/cache/

# How many entries?
ls .pi/taskflows/cache/*.json | wc -l

# Inspect a specific entry (provenance: flowName, phaseId, runId, createdAt)
cat .pi/taskflows/cache/<key>.json | jq '{flowName, phaseId, runId, createdAt, output}'

Common pitfalls

Clearing the cache

There's no clear command in the DSL — the store is just files:

rm -rf .pi/taskflows/cache/

Common errors

Next

Last updated on