The problem is timing.
Business systems do not pause while an agent reads data, calls tools, reasons, waits for approval, or prepares an action.
During that interval:
An account can be frozen.
A payment authorization can be withdrawn.
Inventory can be sold.
A price can change.
A policy can be revised.
A configuration file can be updated.
An API or database can become unreachable.
The agent may still be holding a conclusion derived from the earlier state.
The gap between checking and acting
Most production systems already have important controls.
Payment workflows have rules and approvals. Healthcare operations have authorization and access controls. E-commerce platforms have inventory and fulfillment checks. Engineering teams use GitHub, pull requests, branch protection, and CI/CD.
Those controls remain necessary.
But many of them establish whether something was valid when it was checked. An AI-supported workflow also needs to know whether the evidence supporting its current conclusion is still valid when the action is about to happen.
That is the reasoning-to-action freshness gap.
It resembles a time-of-check-to-time-of-use problem, but it also affects the reasoning derived from the changed source—not only the source itself.
Three examples
Payments
An agent reviews an account, beneficiary status, risk result, and approval records before preparing a payment.
Before execution, a fraud signal changes or the account is placed on legal hold.
The earlier reasoning may have been reasonable when it was produced. But the evidence supporting it is no longer current, so the payment should not proceed on the old conclusion.
Healthcare operations
An automated workflow reads an authorization or scheduling record. The authorization changes—or its source becomes unreachable—while the workflow is underway.
The workflow should not silently treat its earlier snapshot as current.
Freshness validation can complement operational and compliance controls. It does not replace clinical judgment, authorization policy, privacy safeguards, or regulatory review.
E-commerce
An agent prepares an order using inventory, price, fraud, and delivery-capacity evidence.
Before fulfillment, the inventory falls below the requested quantity.
The inventory observation is now stale. The fulfillment reasoning that depended on it must also be reconsidered. An unrelated fraud result, however, may still be current.
That distinction matters. Invalidating everything is safe but inefficient. Invalidating nothing is dangerous.
What FreshCtx does
Today, I’m releasing FreshCtx™ v0.1, an Apache-2.0 open-source freshness and dependency-validation runtime for AI agents.
FreshCtx records the declared sources an agent observed, connects downstream reasoning to those observations, and revalidates the dependencies at a protected action boundary.
It produces four explicit states:
CURRENT: every reachable, declared dependency was successfully revalidated as equivalent.
STALE_SOURCE: an observed source changed.
STALE_REASONING: reasoning depends on stale evidence.
UNVERIFIABLE: FreshCtx could not safely determine whether the dependency is still current.
UNVERIFIABLE never silently becomes CURRENT.
The configured policy can block, warn, allow, or perform one bounded refresh. Blocking is the default.
Install it
FreshCtx supports Python 3.10 through 3.13.
python -m pip install freshctx==0.1.0
To use the optional Postgres adapter:
python -m pip install 'freshctx[postgres]==0.1.0'
No account is required, and the runtime sends no telemetry.
A minimal example
Imagine an agent selecting a deployment target from a configuration file:
from pathlib import Path
from tempfile import TemporaryDirectory
from freshctx import MemoryStore, guard, observe, reasoning
def deploy(target: str) -> None:
print(f"DEPLOYED to {target}")
with TemporaryDirectory() as directory:
root = Path(directory)
config = root / "deployment.env"
audit = root / "freshctx-audit.jsonl"
config.write_text("TARGET=staging\n", encoding="utf-8")
with guard(
policy="block",
store=MemoryStore(),
audit_path=audit,
) as ctx:
source = observe(config)
with reasoning(
"choose_target",
depends_on=[source],
) as decision:
target = "staging"
ctx.run(
deploy,
target,
depends_on=[decision],
)
print(f"FreshCtx state: {ctx.result.state.value}")
print(f"Audit file: {audit}")
Expected output:
DEPLOYED to staging
FreshCtx state: CURRENT
Audit file: /.../freshctx-audit.jsonl
Before deploy() runs, FreshCtx revalidates the declared dependency.
If the configuration changes after observation, the source becomes STALE_SOURCE, the dependent decision becomes STALE_REASONING, and the protected action is blocked.
Dependency-aware invalidation
FreshCtx does not automatically invalidate every conclusion whenever anything changes.
Suppose an audit contains three findings:
retention policy ──> retention finding
access evidence ──> access finding
backup evidence ──> backup finding
If only the retention policy changes, FreshCtx can mark the retention observation STALE_SOURCE and its dependent finding STALE_REASONING.
The access and backup findings can remain CURRENT.
FreshCtx follows the declared dependency graph rather than treating the entire workflow as one undifferentiated cache entry.
What CURRENT does—and does not—prove
CURRENT means that every reachable, declared dependency was successfully revalidated as equivalent under its configured adapter at check time.
It does not prove:
The source itself is true.
The agent’s reasoning is correct.
The action is authorized.
The action is safe or compliant.
Every relevant dependency was declared.
The wider world has not changed.
FreshCtx validates the freshness of declared dependencies. It is not a truth engine, authorization system, policy engine, or compliance certification.
Why CI/CD is not enough
CI/CD establishes that a particular commit passed its configured checks.
FreshCtx answers a different question:
Is the evidence supporting this specific action still current now?
A CI pipeline can verify a commit. FreshCtx can revalidate the declared Git path, file, API response, database row, or MCP resource supporting an agent’s current action.
GitHub and CI/CD remain essential. FreshCtx operates at the reasoning-to-action boundary they do not cover.
Similarly, memory tells an agent what it previously knew. FreshCtx checks whether that knowledge is still current.
Adapters in v0.1
FreshCtx v0.1 includes adapters for:
Filesystem
Git
HTTP
Postgres
MCP
The runtime is local-first, model-neutral, and framework-neutral. It does not require OpenAI, Anthropic, LangChain, or any other particular model or agent framework.
It also includes local JSONL audit events, SQLite and in-memory stores, machine-readable schemas, a documented adapter contract, security semantics, and executable reference scenarios.
Try the drift demos
Clone the repository and run the three reference demonstrations:
git clone https://github.com/Hyperwise-LLC/freshctx.git
cd freshctx
python -m venv .venv
source .venv/bin/activate
python -m pip install .
python examples/coding_file_drift.py
python examples/configuration_api_drift.py
python examples/audit_reasoning_drift.py
The examples demonstrate:
A file changing after an agent observes it.
An API-backed configuration changing while reasoning is underway.
Evidence supporting only one audit finding changing while unrelated findings remain current.
Project links
FreshCtx repository
README and quickstart
FreshCtx v0.1.0 release
PyPI package
Versioned specification
Adapter contract
Security model
Validated reference scenarios
FreshCtx™ is an independent Apache-2.0 open-source project owned and stewarded by Hyperwise LLC.
If you build AI-supported workflows that act on mutable systems, I would be interested to hear where the reasoning-to-action freshness gap appears in your architecture—and which sources your agent would need to revalidate.
_Disclosure: I am associated with the team releasing FreshCtx. AI-assisted editing was used to improve the structure of this article. The technical claims, examples, and final text were reviewed against the released FreshCtx v0.1.0 implementation and documentation.
Top comments (1)
The TOCTOU framing is exactly right. I run into this with my own agent workflows constantly. The fix that actually works for me is a cheap re-validation call right before the write, not a lock. Something like "re-read the three fields you based your decision on, diff against what you had, abort if anything changed." It doubles your read calls but catches the gap between reasoning and acting that no amount of planning-phase cleverness addresses. Deciding which fields matter enough to re-check is where you burn the most time, because re-validating everything defeats the point of having an agent do it faster.