flowscript-agents 0.2.6__tar.gz → 0.2.8__tar.gz

{flowscript_agents-0.2.6 → flowscript_agents-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowscript-agents
-Version: 0.2.6
+Version: 0.2.8
 Summary: Complete agent memory: reasoning queries + vector search + auto-extraction. Decision intelligence for LangGraph, CrewAI, Google ADK, OpenAI Agents SDK, Pydantic AI, smolagents, LlamaIndex, Haystack, and CAMEL-AI.
 Project-URL: Homepage, https://flowscript.org
 Project-URL: Repository, https://github.com/phillipclapham/flowscript-agents
@@ -68,14 +68,14 @@ Description-Content-Type: text/markdown
 
 <h1 align="center">flowscript-agents</h1>
 
-<p align="center"><strong>Agent memory that tracks why you decided, what conflicts, and what's blocked. Not just what was said.</strong></p>
+<p align="center"><strong>Your AI agents make decisions they can't explain. FlowScript makes those decisions queryable.</strong></p>
+
+<p align="center">Drop-in adapters for 9 agent frameworks. Plain text in, typed reasoning queries out.<br>Hash-chained audit trail. Structural compliance. MIT licensed.</p>
 
 [![Tests](https://img.shields.io/badge/tests-584%20passing-brightgreen)](https://github.com/phillipclapham/flowscript-agents) [![PyPI](https://img.shields.io/pypi/v/flowscript-agents)](https://pypi.org/project/flowscript-agents/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/flowscript-agents/)
 
 ---
 
-Plain text in. Typed reasoning queries out:
-
 ```python
 from openai import OpenAI
 from flowscript_agents import UnifiedMemory
@@ -92,18 +92,19 @@ with UnifiedMemory("agent-memory.json", embedder=OpenAIEmbeddings(), llm=llm) as
     mem.add("PostgreSQL gives us rich queries at $15/month but read latency is 10-50ms")
 
     tensions = mem.memory.query.tensions()
-    # → TensionsResult(1 tension, axes=['cost vs budget'])
-    # The LLM detected the $200/month vs $50/month contradiction
-    # and preserved both sides as a queryable tension
+    # → The LLM detected the $200/month vs $50/month contradiction
+    # → and preserved both sides as a queryable tension — not a deletion
 
-    blocked = mem.memory.query.blocked()
-    # → BlockedResult(0 blockers)
+    # Pick any node to trace its reasoning:
+    first_node = mem.memory.nodes[0]
+    why = mem.memory.query.why(first_node.id)
+    # → Full causal chain backward from any decision
 
-    why = mem.memory.query.why(node_id)
-    # → CausalAncestry: full chain backward from any node
+    blocked = mem.memory.query.blocked()
+    # → What's stuck + downstream impact
 ```
 
-Five queries that no vector store can answer — `why()`, `tensions()`, `blocked()`, `alternatives()`, `whatIf()` — over a typed semantic graph. Drop-in adapters for [9 agent frameworks](#works-with-your-stack). Hash-chained audit trail. And when memories contradict, we don't delete the old one — we create a queryable *tension*.
+Five queries that no vector store can answer — `why()`, `tensions()`, `blocked()`, `alternatives()`, `whatIf()` — over a typed reasoning graph. Drop-in adapters for [9 agent frameworks](#works-with-your-stack). Hash-chained audit trail. And when memories contradict, we don't delete — we create a queryable *tension*.
 
 <p align="center">
   <img src="docs/flowscript-demo.png" alt="FlowScript — editor with .fs syntax, D3 reasoning graph, and tensions query results" width="800">
@@ -113,11 +114,11 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 
 ## Why FlowScript
 
-Agent memory stores what happened. FlowScript stores why.
+Every agent framework gives AI agents memory. None of them make that memory queryable.
 
-Most agent infrastructure is converging on authorization — identity, access control, audit trails for *who did what*. That's necessary. But it leaves a gap: your agent can prove it was *allowed* to make a decision, but not *why* it made it. Researchers call this "[strategic blindness](https://arxiv.org/abs/2603.18718)" — memory that tracks content without tracking reasoning.
+Vector stores retrieve content that looks similar. That's useful, but it's not reasoning. When an auditor asks "why did your agent deny that claim?" or a developer asks "what breaks if we change this decision?" — similarity search returns a guess. FlowScript returns the actual typed reasoning chain.
 
-FlowScript sits above your memory store, not instead of it. Google Memory Bank, LangGraph checkpointers, Mem0 — they remember what your agent stored. FlowScript remembers why it decided, what it traded off, and what breaks if you change your mind.
+This is the gap researchers call "[strategic blindness](https://arxiv.org/abs/2603.18718)" — memory that tracks content without tracking reasoning. FlowScript sits above your memory store, not instead of it. Mem0, LangGraph checkpointers, Google Memory Bank — they remember what your agent stored. FlowScript remembers *why it decided*, what it traded off, and what breaks if you change your mind.
 
 ---
 
@@ -337,7 +338,22 @@ result = Memory.verify_audit("agent.audit.jsonl")
 # → AuditVerifyResult(valid=True, total_entries=42, files_verified=1)
 ```
 
-Framework attribution is automatic — every audit entry records which adapter triggered it. Query by time range, event type, adapter, or session. Rotation with gzip compression. `on_event` callback for SIEM integration. [Full audit trail docs →](docs/audit-trail.md)
+Framework attribution is automatic — every audit entry records which adapter triggered it. Query by time range, event type, adapter, or session. Rotation with gzip compression.
+
+**SIEM integration:** `on_event` callback fires for every audit entry. Use `on_event_async=True` for non-blocking dispatch — slow webhooks won't block agent operations:
+
+```python
+from flowscript_agents import Memory, MemoryOptions, AuditConfig
+
+def send_to_siem(entry):
+    requests.post("https://siem.example.com/ingest", json=entry)
+
+mem = Memory.load_or_create("agent.json", options=MemoryOptions(
+    audit=AuditConfig(on_event=send_to_siem, on_event_async=True)
+))
+```
+
+Events are dispatched in order (single worker thread). Callback failures log to stderr but never block audit writes. Call `writer.close()` for graceful shutdown of in-flight callbacks.
 
 ---
 
@@ -365,7 +381,7 @@ Every query touches returned nodes — knowledge that keeps getting queried earn
 **For SDK users** — adapters support context managers that auto-wrap:
 
 ```python
-from flowscript_agents.adapters.langgraph import FlowScriptStore
+from flowscript_agents.langgraph import FlowScriptStore
 
 with FlowScriptStore("agent-memory.json") as store:
     # work happens — all mutations auto-save
@@ -391,6 +407,8 @@ Both the Python and [TypeScript](https://www.npmjs.com/package/flowscript-core)
 
 ## Comparison
 
+Every agent framework gives AI agents memory. None make that memory auditable, typed, or queryable at the reasoning level. That's the layer FlowScript occupies.
+
 | | FlowScript | Mem0 | Vector stores |
 |:---|:---|:---|:---|
 | Find similar content | Vector search | Vector search | Vector search |
@@ -403,7 +421,128 @@ Both the Python and [TypeScript](https://www.npmjs.com/package/flowscript-core)
 | Temporal graduation | Automatic 4-tier | — | — |
 | Token budgeting | 4 strategies | — | — |
 
-Under the hood: a local semantic graph with typed nodes, typed relationships, and typed states. Queries traverse structure — no embeddings required, no LLM calls, no network. Sub-ms on project-scale graphs. Vector search and reasoning queries are orthogonal — use both.
+Under the hood: a local semantic graph with typed nodes, typed relationships, and typed states. Queries traverse structure — no embeddings required, no LLM calls, no network. Sub-ms on project-scale graphs.
+
+Vector search and reasoning queries are orthogonal — use both. Mem0 for retrieval, FlowScript for reasoning. They're different architectural layers.
+
+---
+
+## Enterprise & Compliance
+
+FlowScript's typed reasoning chains are also compliance-ready audit infrastructure. This isn't a separate product — it's a structural property of how FlowScript works.
+
+**EU AI Act coverage:**
+
+| Requirement | Article | How FlowScript satisfies it |
+|:---|:---|:---|
+| Record-keeping | Art. 12 | Hash-chained audit trail, append-only, tamper-evident, 7yr default retention |
+| Transparency | Art. 13 | `why()` queries return typed causal chains — not reconstructions, actual reasoning records |
+| Right to explanation | Art. 86 | `explain()` generates deterministic, reproducible compliance documents from `why()` results |
+| Monitoring | Art. 72 | `on_event` / `on_event_async` callbacks stream audit events to SIEM/monitoring systems |
+
+**Article 86 — Right to Explanation:**
+
+```python
+from flowscript_agents import Memory, explain
+
+mem = Memory.load_or_create("agent.json")
+# ... agent builds reasoning graph during normal work ...
+
+result = mem.query.why(decision_node.id)
+print(explain(result, subject="Applicant ID #4821", audience="legal"))
+```
+
+```
+AUTOMATED DECISION EXPLANATION
+Issued under EU AI Act Article 86 (Right to Explanation)
+
+Subject: Applicant ID #4821
+Decision: loan application denied
+Causal chain depth: 3 steps
+
+CAUSAL SEQUENCE
+  Step 1 (foundational factor): applicant income below minimum requirement
+  Step 2 (derives from): debt-to-income ratio exceeds policy limit
+  Step 3 (derives from): risk assessment: HIGH
+  Outcome: loan application denied
+
+CERTIFICATION
+Generated: 2026-03-27T19:46:46Z
+This explanation is generated from a deterministic causal reasoning graph
+maintained by FlowScript. The complete hash-chained audit trail is available
+upon request and can be verified against the original reasoning record.
+```
+
+Three audience modes: `"general"` (plain English for affected individuals), `"legal"` (formal compliance language with Article 86 citation and hash-chain reference), `"technical"` (structured debug output). No LLM in the loop — the explanation is deterministic and reproducible.
+
+**Via MCP:** call the `explain_decision` tool with a node ID or content search. Same deterministic output, accessible from Claude Code, Cursor, or any MCP client.
+
+**Via framework adapters:** access the underlying Memory through `adapter.memory`:
+
+```python
+from flowscript_agents import explain
+result = adapter.memory.query.why(node_id)
+text = explain(result, audience="legal")
+```
+
+**Enforcement begins August 2026.** Audit trails can't be backdated. Organizations using FlowScript today have unbroken reasoning records from day one. You can turn on logging tomorrow — you can't manufacture the last 18 months of decision provenance.
+
+**Architecture:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Your Agent Framework (LangGraph, CrewAI, ADK, ...) │
+├─────────────────────────────────────────────────────┤
+│  FlowScript SDK — Typed Reasoning Layer             │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
+│  │  Memory   │ │ Queries  │ │ Audit Trail          │ │
+│  │  (graph)  │ │ (5 ops)  │ │ (SHA-256 hash chain) │ │
+│  │         explain()      │ │  on_event_async      │ │
+│  └──────────┘ └──────────┘ └──────────────────────┘ │
+├─────────────────────────────────────────────────────┤
+│  Your Storage (files, database, cloud)              │
+└─────────────────────────────────────────────────────┘
+```
+
+FlowScript doesn't replace your stack. It sits between your agent framework and your storage, adding typed reasoning and audit to whatever you already use.
+
+---
+
+## Security
+
+Three independent CVE clusters dropped in the same week — MCPwned (SSRF via MCP trust boundaries), ClawHub (1,100+ malicious skills in agent marketplaces), and ClawJacked (CVE-2026-25253, CVSS 8.8, 15,200 affected instances). All share the same structural root cause: **unvalidated content flowing through agent invocation paths.**
+
+You can't patch this at the application layer. The invocation path itself is untyped.
+
+FlowScript's typed intermediate representation doesn't prevent every attack class — SSRF and transport-layer poisoning need different tools. What it makes structurally impossible is the deeper problem: **reasoning corruption.** Untraceable decisions, silent contradictions, unaudited state changes — these can't exist in a well-typed FlowScript graph. The type system makes them unrepresentable.
+
+This is the same architectural insight behind [CHERI](https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/): Cambridge proved that making unsafe states hardware-inexpressible eliminates 70% of memory-safety CVEs — structural prevention beats behavioral detection. FlowScript applies this insight at the cognitive layer. The enforcement boundary is different (SDK type system vs. hardware capabilities), but the principle is identical: make the violation unrepresentable rather than hoping to catch it after the fact.
+
+---
+
+## What FlowScript Actually Is
+
+If you've read this far, you're ready for the deeper structure.
+
+The five queries and the audit trail are what FlowScript *does*. Here's what it *is*, and why it matters beyond any single application.
+
+**Musical notation didn't record what musicians were already playing.** Before staff notation, European music was monophonic — single melodies, loosely coordinated. Notation made polyphony possible. Bach's fugues are literally unthinkable without it — not "hard to remember," but impossible to *compose*, because the simultaneous interaction of independent voices requires a representational system precise enough to reason about counterpoint.
+
+Notation expanded the space of possible musical thought.
+
+**FlowScript does the same thing for AI cognition.** It doesn't record what agents are already thinking. It makes a new category of AI reasoning possible — the kind where you can have multiple reasoning chains interacting, where you can query across causal paths, where contradictions become structured tensions instead of silent overwrites. This category of reasoning is impossible in the vector-search paradigm because vector search has no representation for *why*.
+
+**FlowScript's type system makes malformed reasoning unrepresentable.** Every decision traces to a question through alternatives. Every contradiction becomes a typed tension with a named axis. Every state change gets an audited reason. These constraints give FlowScript a property familiar from [type theory](https://en.wikipedia.org/wiki/Type_theory): well-typedness implies safety. A well-formed FlowScript graph can always be queried — no stuck states, no silent contradictions, no untraceable decisions. The type structure doesn't constitute formal proofs in the Curry-Howard sense, but it does what good type systems do: make certain classes of malformed state structurally unrepresentable.
+
+**Compression reveals structure that verbosity hides.** When you force AI reasoning through typed encoding, you force the extraction of structure that would otherwise remain implicit in natural language. This maps to a deep result in information theory: the minimum description of a dataset *is* its structure. Optimal compression and genuine understanding are the same operation. FlowScript's temporal tiers — where knowledge graduates from observation to principle through use — implement this: each compression cycle distills signal from noise, and the resulting structure is *more useful* than the verbose original.
+
+**The metacognitive loop.** When an AI agent writes FlowScript, queries its own reasoning graph, discovers tensions or gaps, and generates new reasoning informed by that structure — it's not just remembering. It's *reasoning about its own reasoning* through a typed, queryable substrate. This is metacognition, and it's the category of thought that FlowScript makes possible that no vector store can touch.
+
+**This isn't just good engineering — there's math behind it.** [Recent work in formal epistemology](https://arxiv.org/abs/2603.17244) applied AGM belief revision postulates — the mathematical framework for rational belief change — and proved that deletion violates core rationality requirements. When you delete a contradicted memory, you destroy information that the formal framework says a rational agent must preserve. FlowScript's RELATE > DELETE approach satisfies these postulates: preserve contradictions as tensions, maintain provenance chains, never destroy reasoning history. The formal result says deletion is irrational. FlowScript is the implementation that takes that seriously.
+
+**FlowScript is infrastructure.** Not a tool. Not a framework. Not a compliance product. Infrastructure — like SQL gave us queryable data, TCP/IP gave us addressable communication, and Git gave us trackable changes. FlowScript gives AI agents queryable reasoning. Everything else — compliance, security, memory, observability — is an application of that infrastructure.
+
+The applications are what you install FlowScript for. The infrastructure is why it matters.
 
 ---
 
@@ -426,4 +565,12 @@ Under the hood: a local semantic graph with typed nodes, typed relationships, an
 
 ---
 
+## Known Limitations
+
+- **Single-writer audit**: Two processes writing the same audit file will corrupt the hash chain. One writer per memory file.
+- **File-based persistence**: JSON file storage via `save()`. For shared or multi-agent setups, use separate memory files per agent.
+- **Extraction quality varies by model**: gpt-4o-mini handles most content well. Complex contradictory content may produce fallback ADDs instead of RELATE operations. Results improve with larger models.
+
+---
+
 MIT. Built by [Phillip Clapham](https://phillipclapham.com).

{flowscript_agents-0.2.6 → flowscript_agents-0.2.8}/README.md

@@ -4,14 +4,14 @@
 
 <h1 align="center">flowscript-agents</h1>
 
-<p align="center"><strong>Agent memory that tracks why you decided, what conflicts, and what's blocked. Not just what was said.</strong></p>
+<p align="center"><strong>Your AI agents make decisions they can't explain. FlowScript makes those decisions queryable.</strong></p>
+
+<p align="center">Drop-in adapters for 9 agent frameworks. Plain text in, typed reasoning queries out.<br>Hash-chained audit trail. Structural compliance. MIT licensed.</p>
 
 [![Tests](https://img.shields.io/badge/tests-584%20passing-brightgreen)](https://github.com/phillipclapham/flowscript-agents) [![PyPI](https://img.shields.io/pypi/v/flowscript-agents)](https://pypi.org/project/flowscript-agents/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/flowscript-agents/)
 
 ---
 
-Plain text in. Typed reasoning queries out:
-
 ```python
 from openai import OpenAI
 from flowscript_agents import UnifiedMemory
@@ -28,18 +28,19 @@ with UnifiedMemory("agent-memory.json", embedder=OpenAIEmbeddings(), llm=llm) as
     mem.add("PostgreSQL gives us rich queries at $15/month but read latency is 10-50ms")
 
     tensions = mem.memory.query.tensions()
-    # → TensionsResult(1 tension, axes=['cost vs budget'])
-    # The LLM detected the $200/month vs $50/month contradiction
-    # and preserved both sides as a queryable tension
+    # → The LLM detected the $200/month vs $50/month contradiction
+    # → and preserved both sides as a queryable tension — not a deletion
 
-    blocked = mem.memory.query.blocked()
-    # → BlockedResult(0 blockers)
+    # Pick any node to trace its reasoning:
+    first_node = mem.memory.nodes[0]
+    why = mem.memory.query.why(first_node.id)
+    # → Full causal chain backward from any decision
 
-    why = mem.memory.query.why(node_id)
-    # → CausalAncestry: full chain backward from any node
+    blocked = mem.memory.query.blocked()
+    # → What's stuck + downstream impact
 ```
 
-Five queries that no vector store can answer — `why()`, `tensions()`, `blocked()`, `alternatives()`, `whatIf()` — over a typed semantic graph. Drop-in adapters for [9 agent frameworks](#works-with-your-stack). Hash-chained audit trail. And when memories contradict, we don't delete the old one — we create a queryable *tension*.
+Five queries that no vector store can answer — `why()`, `tensions()`, `blocked()`, `alternatives()`, `whatIf()` — over a typed reasoning graph. Drop-in adapters for [9 agent frameworks](#works-with-your-stack). Hash-chained audit trail. And when memories contradict, we don't delete — we create a queryable *tension*.
 
 <p align="center">
   <img src="docs/flowscript-demo.png" alt="FlowScript — editor with .fs syntax, D3 reasoning graph, and tensions query results" width="800">
@@ -49,11 +50,11 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 
 ## Why FlowScript
 
-Agent memory stores what happened. FlowScript stores why.
+Every agent framework gives AI agents memory. None of them make that memory queryable.
 
-Most agent infrastructure is converging on authorization — identity, access control, audit trails for *who did what*. That's necessary. But it leaves a gap: your agent can prove it was *allowed* to make a decision, but not *why* it made it. Researchers call this "[strategic blindness](https://arxiv.org/abs/2603.18718)" — memory that tracks content without tracking reasoning.
+Vector stores retrieve content that looks similar. That's useful, but it's not reasoning. When an auditor asks "why did your agent deny that claim?" or a developer asks "what breaks if we change this decision?" — similarity search returns a guess. FlowScript returns the actual typed reasoning chain.
 
-FlowScript sits above your memory store, not instead of it. Google Memory Bank, LangGraph checkpointers, Mem0 — they remember what your agent stored. FlowScript remembers why it decided, what it traded off, and what breaks if you change your mind.
+This is the gap researchers call "[strategic blindness](https://arxiv.org/abs/2603.18718)" — memory that tracks content without tracking reasoning. FlowScript sits above your memory store, not instead of it. Mem0, LangGraph checkpointers, Google Memory Bank — they remember what your agent stored. FlowScript remembers *why it decided*, what it traded off, and what breaks if you change your mind.
 
 ---
 
@@ -273,7 +274,22 @@ result = Memory.verify_audit("agent.audit.jsonl")
 # → AuditVerifyResult(valid=True, total_entries=42, files_verified=1)
 ```
 
-Framework attribution is automatic — every audit entry records which adapter triggered it. Query by time range, event type, adapter, or session. Rotation with gzip compression. `on_event` callback for SIEM integration. [Full audit trail docs →](docs/audit-trail.md)
+Framework attribution is automatic — every audit entry records which adapter triggered it. Query by time range, event type, adapter, or session. Rotation with gzip compression.
+
+**SIEM integration:** `on_event` callback fires for every audit entry. Use `on_event_async=True` for non-blocking dispatch — slow webhooks won't block agent operations:
+
+```python
+from flowscript_agents import Memory, MemoryOptions, AuditConfig
+
+def send_to_siem(entry):
+    requests.post("https://siem.example.com/ingest", json=entry)
+
+mem = Memory.load_or_create("agent.json", options=MemoryOptions(
+    audit=AuditConfig(on_event=send_to_siem, on_event_async=True)
+))
+```
+
+Events are dispatched in order (single worker thread). Callback failures log to stderr but never block audit writes. Call `writer.close()` for graceful shutdown of in-flight callbacks.
 
 ---
 
@@ -301,7 +317,7 @@ Every query touches returned nodes — knowledge that keeps getting queried earn
 **For SDK users** — adapters support context managers that auto-wrap:
 
 ```python
-from flowscript_agents.adapters.langgraph import FlowScriptStore
+from flowscript_agents.langgraph import FlowScriptStore
 
 with FlowScriptStore("agent-memory.json") as store:
     # work happens — all mutations auto-save
@@ -327,6 +343,8 @@ Both the Python and [TypeScript](https://www.npmjs.com/package/flowscript-core)
 
 ## Comparison
 
+Every agent framework gives AI agents memory. None make that memory auditable, typed, or queryable at the reasoning level. That's the layer FlowScript occupies.
+
 | | FlowScript | Mem0 | Vector stores |
 |:---|:---|:---|:---|
 | Find similar content | Vector search | Vector search | Vector search |
@@ -339,7 +357,128 @@ Both the Python and [TypeScript](https://www.npmjs.com/package/flowscript-core)
 | Temporal graduation | Automatic 4-tier | — | — |
 | Token budgeting | 4 strategies | — | — |
 
-Under the hood: a local semantic graph with typed nodes, typed relationships, and typed states. Queries traverse structure — no embeddings required, no LLM calls, no network. Sub-ms on project-scale graphs. Vector search and reasoning queries are orthogonal — use both.
+Under the hood: a local semantic graph with typed nodes, typed relationships, and typed states. Queries traverse structure — no embeddings required, no LLM calls, no network. Sub-ms on project-scale graphs.
+
+Vector search and reasoning queries are orthogonal — use both. Mem0 for retrieval, FlowScript for reasoning. They're different architectural layers.
+
+---
+
+## Enterprise & Compliance
+
+FlowScript's typed reasoning chains are also compliance-ready audit infrastructure. This isn't a separate product — it's a structural property of how FlowScript works.
+
+**EU AI Act coverage:**
+
+| Requirement | Article | How FlowScript satisfies it |
+|:---|:---|:---|
+| Record-keeping | Art. 12 | Hash-chained audit trail, append-only, tamper-evident, 7yr default retention |
+| Transparency | Art. 13 | `why()` queries return typed causal chains — not reconstructions, actual reasoning records |
+| Right to explanation | Art. 86 | `explain()` generates deterministic, reproducible compliance documents from `why()` results |
+| Monitoring | Art. 72 | `on_event` / `on_event_async` callbacks stream audit events to SIEM/monitoring systems |
+
+**Article 86 — Right to Explanation:**
+
+```python
+from flowscript_agents import Memory, explain
+
+mem = Memory.load_or_create("agent.json")
+# ... agent builds reasoning graph during normal work ...
+
+result = mem.query.why(decision_node.id)
+print(explain(result, subject="Applicant ID #4821", audience="legal"))
+```
+
+```
+AUTOMATED DECISION EXPLANATION
+Issued under EU AI Act Article 86 (Right to Explanation)
+
+Subject: Applicant ID #4821
+Decision: loan application denied
+Causal chain depth: 3 steps
+
+CAUSAL SEQUENCE
+  Step 1 (foundational factor): applicant income below minimum requirement
+  Step 2 (derives from): debt-to-income ratio exceeds policy limit
+  Step 3 (derives from): risk assessment: HIGH
+  Outcome: loan application denied
+
+CERTIFICATION
+Generated: 2026-03-27T19:46:46Z
+This explanation is generated from a deterministic causal reasoning graph
+maintained by FlowScript. The complete hash-chained audit trail is available
+upon request and can be verified against the original reasoning record.
+```
+
+Three audience modes: `"general"` (plain English for affected individuals), `"legal"` (formal compliance language with Article 86 citation and hash-chain reference), `"technical"` (structured debug output). No LLM in the loop — the explanation is deterministic and reproducible.
+
+**Via MCP:** call the `explain_decision` tool with a node ID or content search. Same deterministic output, accessible from Claude Code, Cursor, or any MCP client.
+
+**Via framework adapters:** access the underlying Memory through `adapter.memory`:
+
+```python
+from flowscript_agents import explain
+result = adapter.memory.query.why(node_id)
+text = explain(result, audience="legal")
+```
+
+**Enforcement begins August 2026.** Audit trails can't be backdated. Organizations using FlowScript today have unbroken reasoning records from day one. You can turn on logging tomorrow — you can't manufacture the last 18 months of decision provenance.
+
+**Architecture:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Your Agent Framework (LangGraph, CrewAI, ADK, ...) │
+├─────────────────────────────────────────────────────┤
+│  FlowScript SDK — Typed Reasoning Layer             │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
+│  │  Memory   │ │ Queries  │ │ Audit Trail          │ │
+│  │  (graph)  │ │ (5 ops)  │ │ (SHA-256 hash chain) │ │
+│  │         explain()      │ │  on_event_async      │ │
+│  └──────────┘ └──────────┘ └──────────────────────┘ │
+├─────────────────────────────────────────────────────┤
+│  Your Storage (files, database, cloud)              │
+└─────────────────────────────────────────────────────┘
+```
+
+FlowScript doesn't replace your stack. It sits between your agent framework and your storage, adding typed reasoning and audit to whatever you already use.
+
+---
+
+## Security
+
+Three independent CVE clusters dropped in the same week — MCPwned (SSRF via MCP trust boundaries), ClawHub (1,100+ malicious skills in agent marketplaces), and ClawJacked (CVE-2026-25253, CVSS 8.8, 15,200 affected instances). All share the same structural root cause: **unvalidated content flowing through agent invocation paths.**
+
+You can't patch this at the application layer. The invocation path itself is untyped.
+
+FlowScript's typed intermediate representation doesn't prevent every attack class — SSRF and transport-layer poisoning need different tools. What it makes structurally impossible is the deeper problem: **reasoning corruption.** Untraceable decisions, silent contradictions, unaudited state changes — these can't exist in a well-typed FlowScript graph. The type system makes them unrepresentable.
+
+This is the same architectural insight behind [CHERI](https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/): Cambridge proved that making unsafe states hardware-inexpressible eliminates 70% of memory-safety CVEs — structural prevention beats behavioral detection. FlowScript applies this insight at the cognitive layer. The enforcement boundary is different (SDK type system vs. hardware capabilities), but the principle is identical: make the violation unrepresentable rather than hoping to catch it after the fact.
+
+---
+
+## What FlowScript Actually Is
+
+If you've read this far, you're ready for the deeper structure.
+
+The five queries and the audit trail are what FlowScript *does*. Here's what it *is*, and why it matters beyond any single application.
+
+**Musical notation didn't record what musicians were already playing.** Before staff notation, European music was monophonic — single melodies, loosely coordinated. Notation made polyphony possible. Bach's fugues are literally unthinkable without it — not "hard to remember," but impossible to *compose*, because the simultaneous interaction of independent voices requires a representational system precise enough to reason about counterpoint.
+
+Notation expanded the space of possible musical thought.
+
+**FlowScript does the same thing for AI cognition.** It doesn't record what agents are already thinking. It makes a new category of AI reasoning possible — the kind where you can have multiple reasoning chains interacting, where you can query across causal paths, where contradictions become structured tensions instead of silent overwrites. This category of reasoning is impossible in the vector-search paradigm because vector search has no representation for *why*.
+
+**FlowScript's type system makes malformed reasoning unrepresentable.** Every decision traces to a question through alternatives. Every contradiction becomes a typed tension with a named axis. Every state change gets an audited reason. These constraints give FlowScript a property familiar from [type theory](https://en.wikipedia.org/wiki/Type_theory): well-typedness implies safety. A well-formed FlowScript graph can always be queried — no stuck states, no silent contradictions, no untraceable decisions. The type structure doesn't constitute formal proofs in the Curry-Howard sense, but it does what good type systems do: make certain classes of malformed state structurally unrepresentable.
+
+**Compression reveals structure that verbosity hides.** When you force AI reasoning through typed encoding, you force the extraction of structure that would otherwise remain implicit in natural language. This maps to a deep result in information theory: the minimum description of a dataset *is* its structure. Optimal compression and genuine understanding are the same operation. FlowScript's temporal tiers — where knowledge graduates from observation to principle through use — implement this: each compression cycle distills signal from noise, and the resulting structure is *more useful* than the verbose original.
+
+**The metacognitive loop.** When an AI agent writes FlowScript, queries its own reasoning graph, discovers tensions or gaps, and generates new reasoning informed by that structure — it's not just remembering. It's *reasoning about its own reasoning* through a typed, queryable substrate. This is metacognition, and it's the category of thought that FlowScript makes possible that no vector store can touch.
+
+**This isn't just good engineering — there's math behind it.** [Recent work in formal epistemology](https://arxiv.org/abs/2603.17244) applied AGM belief revision postulates — the mathematical framework for rational belief change — and proved that deletion violates core rationality requirements. When you delete a contradicted memory, you destroy information that the formal framework says a rational agent must preserve. FlowScript's RELATE > DELETE approach satisfies these postulates: preserve contradictions as tensions, maintain provenance chains, never destroy reasoning history. The formal result says deletion is irrational. FlowScript is the implementation that takes that seriously.
+
+**FlowScript is infrastructure.** Not a tool. Not a framework. Not a compliance product. Infrastructure — like SQL gave us queryable data, TCP/IP gave us addressable communication, and Git gave us trackable changes. FlowScript gives AI agents queryable reasoning. Everything else — compliance, security, memory, observability — is an application of that infrastructure.
+
+The applications are what you install FlowScript for. The infrastructure is why it matters.
 
 ---
 
@@ -362,4 +501,12 @@ Under the hood: a local semantic graph with typed nodes, typed relationships, an
 
 ---
 
+## Known Limitations
+
+- **Single-writer audit**: Two processes writing the same audit file will corrupt the hash chain. One writer per memory file.
+- **File-based persistence**: JSON file storage via `save()`. For shared or multi-agent setups, use separate memory files per agent.
+- **Extraction quality varies by model**: gpt-4o-mini handles most content well. Complex contradictory content may produce fallback ADDs instead of RELATE operations. Results improve with larger models.
+
+---
+
 MIT. Built by [Phillip Clapham](https://phillipclapham.com).

{flowscript_agents-0.2.6 → flowscript_agents-0.2.8}/flowscript_agents/__init__.py

@@ -27,6 +27,7 @@ Usage:
 """
 
 from .audit import AuditConfig, AuditQueryResult, AuditVerifyResult
+from .cloud import CloudClient, CloudFlushResult, CloudWitness
 from .memory import (
     Memory,
     MemoryOptions,
@@ -42,12 +43,17 @@ from .memory import (
     SessionWrapResult,
 )
 from .unified import UnifiedMemory
+from .explain import explain
 
-__version__ = "0.2.5"
+__version__ = "0.2.8"
 __all__ = [
+    "explain",
     "AuditConfig",
     "AuditQueryResult",
     "AuditVerifyResult",
+    "CloudClient",
+    "CloudFlushResult",
+    "CloudWitness",
     "Memory",
     "MemoryOptions",
     "NodeRef",

{flowscript_agents-0.2.6 → flowscript_agents-0.2.8}/flowscript_agents/audit.py

@@ -20,11 +20,13 @@ File layout:
 from __future__ import annotations
 
 import gzip
+import atexit
 import hashlib
 import json
 import os
 import shutil
 import sys
+from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -58,6 +60,10 @@ class AuditConfig:
             full entry dict AFTER disk write. Callback failure never blocks
             audit persistence. Use for SIEM integration, Observatory, or custom
             monitoring.
+        on_event_async: If True, fire on_event in a background thread so slow
+            webhooks or network I/O don't block agent operations. Events are
+            dispatched in order (single worker thread). Callback errors are
+            logged to stderr but never propagate. Default False (synchronous).
     """
 
     rotation: str = "monthly"
@@ -67,6 +73,7 @@ class AuditConfig:
     verbosity: str = "standard"
     encryption: Literal["none", "aes-256-gcm"] = "none"
     on_event: Optional[Callable[[dict[str, Any]], None]] = None
+    on_event_async: bool = False
 
     def __post_init__(self) -> None:
         if self.encryption != "none":
@@ -147,6 +154,34 @@ class AuditWriter:
         self._current_period = ""
         self._initialized = False
         self._in_cleanup = False  # Guard against recursive cleanup → write → rotate → cleanup
+        self._executor: Optional[ThreadPoolExecutor] = None
+
+    def _get_executor(self) -> ThreadPoolExecutor:
+        """Lazily create the background executor for async on_event dispatch."""
+        if self._executor is None:
+            self._executor = ThreadPoolExecutor(
+                max_workers=1,
+                thread_name_prefix="audit_on_event",
+            )
+            atexit.register(self.close)
+        return self._executor
+
+    def close(self) -> None:
+        """Shutdown the async executor, waiting for all pending callbacks to complete.
+
+        Call this to ensure in-flight on_event callbacks (e.g. webhook POSTs)
+        have finished before process exit. Safe to call multiple times.
+        """
+        if self._executor is not None:
+            self._executor.shutdown(wait=True)
+            self._executor = None
+
+    def _fire_on_event(self, entry: dict[str, Any]) -> None:
+        """Fire the on_event callback with error isolation."""
+        try:
+            self._config.on_event(entry)  # type: ignore[misc]
+        except Exception as e:
+            print(f"AuditWriter: on_event callback failed: {e}", file=sys.stderr)
 
     # -------------------------------------------------------------------------
     # Path derivation
@@ -371,10 +406,10 @@ class AuditWriter:
 
         # Fire on_event callback (failure must never block audit, but log to stderr)
         if self._config.on_event:
-            try:
-                self._config.on_event(entry)
-            except Exception as e:
-                print(f"AuditWriter: on_event callback failed: {e}", file=sys.stderr)
+            if self._config.on_event_async:
+                self._get_executor().submit(self._fire_on_event, entry)
+            else:
+                self._fire_on_event(entry)
 
         return entry