{"slug": "freshctx-invalidate-ai-reasoning-when-its-evidence-changes", "title": "FreshCtx – Invalidate AI reasoning when its evidence changes", "summary": "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.", "body_md": "Don’t let AI agents act on stale reasoning.\n\nFreshCtx™ 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.\n\nFreshCtx 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.\n\nPrerequisites: Python 3.10–3.13 and Git. The Git executable is required by the Git adapter and its compatibility tests.\n\nAfter FreshCtx v0.1.0 is published to PyPI, install the release package with:\n\n```\npython -m pip install freshctx==0.1.0\n```\n\nUntil publication—or when working from source—clone and install the repository:\n\n```\ngit clone https://github.com/Hyperwise-LLC/freshctx.git\ncd freshctx\npython -m venv .venv\n```\n\nActivate the environment on macOS or Linux:\n\n```\nsource .venv/bin/activate\n```\n\nOn Windows PowerShell:\n\n```\n.\\.venv\\Scripts\\Activate.ps1\n```\n\nOn Windows Command Prompt:\n\n```\n.venv\\Scripts\\activate.bat\n```\n\nInstall the source checkout and run the executable quickstart:\n\n```\npython -m pip install .\npython examples/quickstart.py\n```\n\nExpected output includes:\n\n```\nDEPLOYED to staging\nFreshCtx state: CURRENT\nAudit events: 4\n```\n\nThe complete quickstart is deliberately small:\n\n``` python\nfrom pathlib import Path\nfrom tempfile import TemporaryDirectory\n\nfrom freshctx import MemoryStore, guard, observe, reasoning\n\ndef deploy(target: str) -> None:\n    print(f\"DEPLOYED to {target}\")\n\nwith TemporaryDirectory() as directory:\n    root = Path(directory)\n    config = root / \"deployment.env\"\n    audit = root / \"freshctx-audit.jsonl\"\n    config.write_text(\"TARGET=staging\\n\", encoding=\"utf-8\")\n\n    with guard(policy=\"block\", store=MemoryStore(), audit_path=audit) as ctx:\n        source = observe(config)\n        with reasoning(\"choose_target\", depends_on=[source]) as decision:\n            target = \"staging\"\n        ctx.run(deploy, target, depends_on=[decision])\n\n    print(f\"FreshCtx state: {ctx.result.state.value}\")\n    print(f\"Audit events: {sum(1 for _ in audit.open(encoding='utf-8'))}\")\n```\n\nThe frozen v0.1 contract includes `ObservationToken`\n\n, `ReasoningNode`\n\n, `CheckResult`\n\n, and `FreshnessStatus`\n\n. A `ReasoningNode`\n\ncarries its canonical, sorted, duplicate-free dependency identifiers; there is no separate public edge object.\n\nThe first v0.1 vertical slice includes:\n\n`ObservationToken`\n\nand`ReasoningNode`\n\ndata models- filesystem observation and validation\n- Git repository- and path-scoped observation and validation\n- transitive freshness evaluation\n`CURRENT`\n\n,`STALE_SOURCE`\n\n,`STALE_REASONING`\n\n, and`UNVERIFIABLE`\n\n- default blocking policy plus\n`warn`\n\nand`allow`\n\n- SQLite and in-memory stores\n- local JSONL audit events\n- Filesystem, Git, HTTP, Postgres, and MCP adapters\n\nThe following conceptual example shows where FreshCtx fits around an existing agent:\n\n``` python\nfrom freshctx import guard, observe, reasoning\n\nwith guard(policy=\"block\") as ctx:\n    config = observe(\"config.yaml\")\n    with reasoning(\"deployment_target\", depends_on=[config]) as decision:\n        target = choose_target(config)\n    result = ctx.run(agent.run, task, depends_on=[decision])\n```\n\nIf `config.yaml`\n\nchanges before the protected boundary, FreshCtx marks the observation `STALE_SOURCE`\n\n, the dependent decision `STALE_REASONING`\n\n, and raises `FreshnessBlocked`\n\n.\n\n`ctx.run()`\n\nperforms the freshness check and records the allow decision before it invokes the protected function. Use `ctx.protect()`\n\nonly for output validation where no side effect has already occurred.\n\n``` python\npython -c \"import freshctx; print(freshctx.FreshnessStatus.CURRENT.value)\"\n```\n\nRun all three reference demos:\n\n```\npython examples/coding_file_drift.py\npython examples/configuration_api_drift.py\npython examples/audit_reasoning_drift.py\n```\n\nExpected final lines are `STALE_SOURCE`\n\n, `STALE_SOURCE`\n\n, and `only finding-a invalidated`\n\n, respectively.\n\nRun the nine realistic business acceptance scenarios:\n\n```\npython examples/real_world_success_cases.py --output success-cases.json\n```\n\nThe command covers banking, e-commerce, audit, insurance, healthcare operations,\nprocurement, customer service, IT/security, and legal operations. See\n[ docs/SUCCESS_CASES.md](/Hyperwise-LLC/freshctx/blob/main/docs/SUCCESS_CASES.md) for the method, results, and limits.\n\nRun the complete test suite from an installed checkout:\n\n```\npython -m pip install '.[test]'\npython -m unittest discover -s tests -v\n```\n\nFreshCtx is licensed under Apache-2.0, model- and framework-neutral, local-first, and free of required accounts or telemetry.\n\nFreshCtx 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.\n\nThe 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).\n\nHyperwise 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.\n\nGitHub 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.\n\nFreshCtx 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.\n\nMemory systems can retain what an agent knew. FreshCtx is not memory: it checks whether reachable, declared evidence still matches its recorded fingerprint.\n\n`CURRENT`\n\nproves 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`\n\nfollows the configured policy and never silently becomes `CURRENT`\n\n.\n\nSee [ 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.\n\nUnless `audit_path`\n\nis supplied, FreshCtx appends JSON Lines events to `.freshctx/audit.jsonl`\n\n, relative to the process working directory. The file stays local; FreshCtx does not upload audit events or send telemetry.\n\nSet an explicit location when the application has its own data directory:\n\n```\nwith guard(audit_path=\"var/audit/freshctx.jsonl\") as ctx:\n    ...\n```\n\nEach line is one event such as `observed`\n\n, `policy_applied`\n\n, or `action_allowed`\n\n. Treat audit files as application data: restrict access, define retention, and avoid putting them in source control.\n\nSQLite records are written to `.freshctx/freshctx.db`\n\nunless a store path is supplied; SQLite may also create `-wal`\n\nand `-shm`\n\ncompanion 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`\n\n/`-shm`\n\ncompanions, and the configured JSONL audit file. Deletion is irreversible; follow your application retention policy first.\n\nAll adapters use the same `observe()`\n\nentry point. Revalidation occurs when `ctx.check()`\n\n, `ctx.run()`\n\n, or a protected boundary evaluates the token or dependent reasoning.\n\nThe examples below assume:\n\n``` python\nfrom freshctx import guard, observe\nwith guard(policy=\"allow\") as ctx:\n    token = observe(\"README.md\", root=\".\")\n    print(ctx.check(token).state.value)\n```\n\nThe 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`\n\n, resolved file symlinks must remain inside `root`\n\n; directory symlink traversal is rejected as unsupported. Limit or boundary failures are `UNVERIFIABLE`\n\n, never `CURRENT`\n\n. 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.\n\n```\nwith guard(policy=\"allow\") as ctx:\n    token = observe(\".\", adapter=\"git\", scope=\"path\", path=\"README.md\")\n    print(ctx.check(token).state.value)\nwith guard(policy=\"allow\") as ctx:\n    token = observe(\"https://example.com/\", adapter=\"http\", timeout=2.0)\n    print(ctx.check(token).state.value)\n```\n\nUse a read-only endpoint. Authentication headers remain in process-local adapter state and should come from the application's secret store.\n\nInstall the optional dependency first:\n\n```\npython -m pip install '.[postgres]'\n```\n\nAfter the public package is available, the equivalent command is `python -m pip install 'freshctx[postgres]==0.1.0'`\n\n.\n\n``` python\nimport os\n\nwith guard(policy=\"allow\") as ctx:\n    token = observe(\n        os.environ[\"DATABASE_URL\"],\n        adapter=\"postgres\",\n        query=\"SELECT id, status FROM jobs WHERE status = %s\",\n        params=[\"ready\"],\n        ordered=False,\n        timeout=2.0,\n    )\n    print(ctx.check(token).state.value)\n```\n\nPostgres validation is read-only. DSNs, raw query text, and parameters are not persisted in observation tokens.\n\nPostgres 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`\n\n.\n\nPass a safe, read-only callable from the application's MCP client:\n\n``` python\ndef read_policy_resource():\n    # Replace this body with the application's read-only MCP client call.\n    return {\"uri\": \"policy://deployment\", \"version\": 1}\n\nwith guard(policy=\"allow\") as ctx:\n    token = observe(\n        \"policy-server\",\n        adapter=\"mcp\",\n        name=\"read_resource\",\n        arguments={\"uri\": \"policy://deployment\"},\n        reader=read_policy_resource,\n        safe=True,\n    )\n    print(ctx.check(token).state.value)\n```\n\nUnsafe or non-idempotent MCP operations are `UNVERIFIABLE`\n\n; do not use them as validation readers. See `docs/ADAPTER_CONTRACT.md`\n\nfor the complete extension contract.\n\nFreshCtx 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.\n\n- FreshCtx product site:\n[https://freshctx.com](https://freshctx.com)(the complete site is being developed separately) - Source repository:\n[https://github.com/Hyperwise-LLC/freshctx](https://github.com/Hyperwise-LLC/freshctx) - Hyperwise LLC corporate site:\n[https://hyperwise.io](https://hyperwise.io) - Community support: see\n`SUPPORT.md`\n\nCommunity 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`\n\n. This does not announce a hosted service, control plane, enterprise edition, or SLA.\n\n`ARCHITECTURE.md`\n\n— components, data flow, trust boundaries, and extension model`API.md`\n\n— frozen v0.1 Python API contract`schemas/`\n\n— machine-readable v0.1 object contracts`adr/`\n\n— accepted architecture decisions`BACKLOG.md`\n\n— issue-ready implementation and release plan`PROJECT_STATUS.md`\n\n— implemented versus remaining work`SPEC.md`\n\n— normative, versioned v0.1 specification`docs/ADAPTER_CONTRACT.md`\n\n— adapter behavior and failure contract`docs/SECURITY_MODEL.md`\n\n— trust boundaries and fail-closed behavior`docs/PERFORMANCE.md`\n\n— intended scale and performance boundaries`docs/FAQ.md`\n\n— product boundaries and common implementation questions`GOVERNANCE.md`\n\nand`RELEASING.md`\n\n— stewardship and private-to-public release process\n\n```\npython -m pip install '.[dev]'\npython scripts/release_check.py\npython -m build\n```\n\nThe 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.", "url": "https://wpnews.pro/news/freshctx-invalidate-ai-reasoning-when-its-evidence-changes", "canonical_source": "https://github.com/Hyperwise-LLC/freshctx", "published_at": "2026-08-28 22:29:39+00:00", "updated_at": "2026-08-28 22:48:20.039616+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Hyperwise LLC", "FreshCtx", "PyPI", "Git"], "alternates": {"html": "https://wpnews.pro/news/freshctx-invalidate-ai-reasoning-when-its-evidence-changes", "markdown": "https://wpnews.pro/news/freshctx-invalidate-ai-reasoning-when-its-evidence-changes.md", "text": "https://wpnews.pro/news/freshctx-invalidate-ai-reasoning-when-its-evidence-changes.txt", "jsonld": "https://wpnews.pro/news/freshctx-invalidate-ai-reasoning-when-its-evidence-changes.jsonld"}}