FreshCtx – Invalidate AI reasoning when its evidence changes

Hyperwise LLC released FreshCtx v0.1.0, an Apache-2.0 open-source pre-action freshness and dependency-validation layer for AI agents that blocks actions when underlying evidence changes. The tool records source observations, links reasoning to those observations, and revalidates dependencies before protected actions, supporting filesystem, Git, HTTP, Postgres, and MCP adapters with a default blocking policy.

Don’t let AI agents act on stale reasoning. FreshCtx™ is Apache-2.0 software owned and stewarded by Hyperwise LLC as an independent open-source project. The software is model-neutral, framework-neutral, local-first, requires no account, and sends no telemetry. FreshCtx is a pre-action freshness and dependency-validation layer for AI agents. It records source observations, links reasoning to those observations, and revalidates declared dependencies before a protected action or output. Prerequisites: Python 3.10–3.13 and Git. The Git executable is required by the Git adapter and its compatibility tests. After FreshCtx v0.1.0 is published to PyPI, install the release package with: python -m pip install freshctx==0.1.0 Until publication—or when working from source—clone and install the repository: git clone https://github.com/Hyperwise-LLC/freshctx.git cd freshctx python -m venv .venv Activate the environment on macOS or Linux: source .venv/bin/activate On Windows PowerShell: .\.venv\Scripts\Activate.ps1 On Windows Command Prompt: .venv\Scripts\activate.bat Install the source checkout and run the executable quickstart: python -m pip install . python examples/quickstart.py Expected output includes: DEPLOYED to staging FreshCtx state: CURRENT Audit events: 4 The complete quickstart is deliberately small: python 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 events: {sum 1 for in audit.open encoding='utf-8' }" The frozen v0.1 contract includes ObservationToken , ReasoningNode , CheckResult , and FreshnessStatus . A ReasoningNode carries its canonical, sorted, duplicate-free dependency identifiers; there is no separate public edge object. The first v0.1 vertical slice includes: ObservationToken and ReasoningNode data models- filesystem observation and validation - Git repository- and path-scoped observation and validation - transitive freshness evaluation CURRENT , STALE SOURCE , STALE REASONING , and UNVERIFIABLE - default blocking policy plus warn and allow - SQLite and in-memory stores - local JSONL audit events - Filesystem, Git, HTTP, Postgres, and MCP adapters The following conceptual example shows where FreshCtx fits around an existing agent: python from freshctx import guard, observe, reasoning with guard policy="block" as ctx: config = observe "config.yaml" with reasoning "deployment target", depends on= config as decision: target = choose target config result = ctx.run agent.run, task, depends on= decision If config.yaml changes before the protected boundary, FreshCtx marks the observation STALE SOURCE , the dependent decision STALE REASONING , and raises FreshnessBlocked . ctx.run performs the freshness check and records the allow decision before it invokes the protected function. Use ctx.protect only for output validation where no side effect has already occurred. python python -c "import freshctx; print freshctx.FreshnessStatus.CURRENT.value " Run all three reference demos: python examples/coding file drift.py python examples/configuration api drift.py python examples/audit reasoning drift.py Expected final lines are STALE SOURCE , STALE SOURCE , and only finding-a invalidated , respectively. Run the nine realistic business acceptance scenarios: python examples/real world success cases.py --output success-cases.json The command covers banking, e-commerce, audit, insurance, healthcare operations, procurement, customer service, IT/security, and legal operations. See docs/SUCCESS CASES.md /Hyperwise-LLC/freshctx/blob/main/docs/SUCCESS CASES.md for the method, results, and limits. Run the complete test suite from an installed checkout: python -m pip install '. test ' python -m unittest discover -s tests -v FreshCtx is licensed under Apache-2.0, model- and framework-neutral, local-first, and free of required accounts or telemetry. FreshCtx is licensed under the Apache License 2.0 /Hyperwise-LLC/freshctx/blob/main/LICENSE . You may use, modify, and distribute the software—including in commercial applications—subject to the license terms. No account, paid plan, or commercial agreement with Hyperwise LLC is required to use FreshCtx. The software license does not grant permission to use the FreshCtx™ name, logo, or branding in a way that implies endorsement or creates confusion about the source of a modified product. See TRADEMARKS.md /Hyperwise-LLC/freshctx/blob/main/TRADEMARKS.md . Hyperwise LLC may separately offer architecture, integration, deployment, managed connectors, organizational controls, and support services. These services are optional, are not required to use the open-source FreshCtx runtime, and remain separate from FreshCtx core. Possible future commercial products are not part of the v0.1 open-source project unless expressly released under its license. GitHub branch protection and CI/CD determine whether a particular commit passed its configured checks. FreshCtx determines whether the specific files, Git state, APIs, database rows, or MCP resources supporting an agent's current action are still valid when that action is about to occur. FreshCtx does not replace GitHub, pull requests, branch protection, or CI/CD. It closes the reasoning-to-action freshness gap, including for mutable sources outside Git. Path-scoped Git validation prevents an unrelated repository change from invalidating every observation. Memory systems can retain what an agent knew. FreshCtx is not memory: it checks whether reachable, declared evidence still matches its recorded fingerprint. CURRENT proves only that every reachable, declared dependency was successfully revalidated as equivalent under its configured adapter at check time. It does not prove source truth, reasoning correctness, authorization, safety, compliance, or global reality. If a source cannot be checked, UNVERIFIABLE follows the configured policy and never silently becomes CURRENT . See docs/FAQ.md /Hyperwise-LLC/freshctx/blob/main/docs/FAQ.md for concise answers about CI/CD, memory, selective invalidation, compliance controls, and optional adapters. Unless audit path is supplied, FreshCtx appends JSON Lines events to .freshctx/audit.jsonl , relative to the process working directory. The file stays local; FreshCtx does not upload audit events or send telemetry. Set an explicit location when the application has its own data directory: with guard audit path="var/audit/freshctx.jsonl" as ctx: ... Each line is one event such as observed , policy applied , or action allowed . Treat audit files as application data: restrict access, define retention, and avoid putting them in source control. SQLite records are written to .freshctx/freshctx.db unless a store path is supplied; SQLite may also create -wal and -shm companion files. Records and audit events can contain absolute local paths. To remove local FreshCtx data, stop every process using the store, then delete the database, its -wal / -shm companions, and the configured JSONL audit file. Deletion is irreversible; follow your application retention policy first. All adapters use the same observe entry point. Revalidation occurs when ctx.check , ctx.run , or a protected boundary evaluates the token or dependent reasoning. The examples below assume: python from freshctx import guard, observe with guard policy="allow" as ctx: token = observe "README.md", root="." print ctx.check token .state.value The filesystem adapter streams file hashing and defaults to 16 MiB per file, 64 MiB total, and 10,000 traversed entries. Symlinks are fingerprinted without following them by default. If follow symlinks=True , resolved file symlinks must remain inside root ; directory symlink traversal is rejected as unsupported. Limit or boundary failures are UNVERIFIABLE , never CURRENT . Raw file contents are not stored, but absolute paths and safe fingerprint metadata are. Supply only trusted, intentionally scoped paths; FreshCtx does not secret-scan observed files. with guard policy="allow" as ctx: token = observe ".", adapter="git", scope="path", path="README.md" print ctx.check token .state.value with guard policy="allow" as ctx: token = observe "https://example.com/", adapter="http", timeout=2.0 print ctx.check token .state.value Use a read-only endpoint. Authentication headers remain in process-local adapter state and should come from the application's secret store. Install the optional dependency first: python -m pip install '. postgres ' After the public package is available, the equivalent command is python -m pip install 'freshctx postgres ==0.1.0' . python import os with guard policy="allow" as ctx: token = observe os.environ "DATABASE URL" , adapter="postgres", query="SELECT id, status FROM jobs WHERE status = %s", params= "ready" , ordered=False, timeout=2.0, print ctx.check token .state.value Postgres validation is read-only. DSNs, raw query text, and parameters are not persisted in observation tokens. Postgres is an optional observed-source adapter, not a FreshCtx storage backend. Revalidation state such as credentials remains process-local; after restart, the application must reconstruct the configured adapter state or checks safely return UNVERIFIABLE . Pass a safe, read-only callable from the application's MCP client: python def read policy resource : Replace this body with the application's read-only MCP client call. return {"uri": "policy://deployment", "version": 1} with guard policy="allow" as ctx: token = observe "policy-server", adapter="mcp", name="read resource", arguments={"uri": "policy://deployment"}, reader=read policy resource, safe=True, print ctx.check token .state.value Unsafe or non-idempotent MCP operations are UNVERIFIABLE ; do not use them as validation readers. See docs/ADAPTER CONTRACT.md for the complete extension contract. FreshCtx does not provide an MCP transport or client. The application supplies and reconstructs the safe-reader callback after process restart. External network calls occur only when the application explicitly selects an external adapter such as HTTP, Postgres, or MCP. - FreshCtx product site: https://freshctx.com https://freshctx.com the complete site is being developed separately - Source repository: https://github.com/Hyperwise-LLC/freshctx https://github.com/Hyperwise-LLC/freshctx - Hyperwise LLC corporate site: https://hyperwise.io https://hyperwise.io - Community support: see SUPPORT.md Community includes the complete v0.1 runtime, five adapters, schemas, examples, and compatibility tests for local developer use. Using FreshCtx in a consequential or regulated workflow? Hyperwise LLC is working with design partners on organizational freshness controls, managed integrations, evidence, and deployment support. Contact freshctx@hyperwise.io . This does not announce a hosted service, control plane, enterprise edition, or SLA. ARCHITECTURE.md — components, data flow, trust boundaries, and extension model API.md — frozen v0.1 Python API contract schemas/ — machine-readable v0.1 object contracts adr/ — accepted architecture decisions BACKLOG.md — issue-ready implementation and release plan PROJECT STATUS.md — implemented versus remaining work SPEC.md — normative, versioned v0.1 specification docs/ADAPTER CONTRACT.md — adapter behavior and failure contract docs/SECURITY MODEL.md — trust boundaries and fail-closed behavior docs/PERFORMANCE.md — intended scale and performance boundaries docs/FAQ.md — product boundaries and common implementation questions GOVERNANCE.md and RELEASING.md — stewardship and private-to-public release process python -m pip install '. dev ' python scripts/release check.py python -m build The private-phase release workflow is manual and build-only. It tests the release, builds the wheel and source archive, verifies wheel installation, and stores private workflow artifacts. It contains no public publishing job.