flowscript-agents 0.2.0__tar.gz → 0.2.1__tar.gz

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowscript-agents
-Version: 0.2.0
+Version: 0.2.1
 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, CAMEL-AI, and Vercel AI SDK.
 Project-URL: Homepage, https://flowscript.org
 Project-URL: Repository, https://github.com/phillipclapham/flowscript-agents
@@ -83,19 +83,20 @@ llm = lambda prompt: (client.chat.completions.create(
 ).choices[0].message.content or "")
 
 with UnifiedMemory("agent-memory.json", embedder=OpenAIEmbeddings(), llm=llm) as mem:
-    mem.add("We chose Redis for session storage — sub-ms reads are critical for UX")
-    mem.add("Redis cluster costs are killing us at $200/mo for 3 nodes")
-    mem.add("Decided: switch to PostgreSQL — handles our scale at $15/mo")
+    mem.add("Redis gives sub-ms reads which is critical for our UX requirements")
+    mem.add("Redis clustering costs $200/month which exceeds our infrastructure budget of $50/month")
+    mem.add("PostgreSQL gives us rich queries at $15/month but read latency is 10-50ms")
 
-    print(mem.memory.query.tensions())
-    # → Tension: "sub-ms reads critical for UX" vs "cluster costs $200/mo"
-    #   axis: "performance vs cost"
+    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
 
-    print(mem.memory.query.blocked())
-    # → what's stuck and why, with downstream impact
+    blocked = mem.memory.query.blocked()
+    # → BlockedResult(0 blockers)
 
-    print(mem.memory.query.why(node_id))
-    # → full causal chain backward from any decision
+    why = mem.memory.query.why(node_id)
+    # → CausalAncestry: full chain backward from any node
 ```
 
 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*.
@@ -128,7 +129,9 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 pip install flowscript-agents
 ```
 
-Auto-detects your API key and configures the full stack — vector search, typed extraction, and contradiction handling. Also supports `ANTHROPIC_API_KEY`. 11 tools, zero additional setup.
+Auto-detects your API key and configures the full stack: vector search, typed extraction, and contradiction handling. Also supports `ANTHROPIC_API_KEY`. 13 reasoning tools.
+
+**Then add the [CLAUDE.md snippet](examples/CLAUDE.md.example) to your project.** This is what turns tools into a workflow. It tells your agent *when* to record decisions, surface tensions before new choices, and check blockers at session start. Without it, the tools are available but passive. With it, your agent proactively tracks your project's reasoning.
 
 ### Python SDK
 
@@ -155,6 +158,31 @@ FlowScript operates at three levels. Pick where you start:
 
 ---
 
+## First 5 Minutes
+
+With the MCP server running and the CLAUDE.md snippet in your project, try this conversation:
+
+> "I need to decide between PostgreSQL and MongoDB for our user data. We need ACID compliance for payments but flexibility for user profiles."
+
+Your agent stores the decision context, tradeoffs, and rationale automatically. Now introduce contradictory information:
+
+> "Actually, I've been looking at DynamoDB. The scale requirements might matter more than I thought."
+
+Now ask:
+
+> "What tensions do we have in our architecture decisions?"
+
+FlowScript preserved both perspectives (PostgreSQL's ACID compliance vs DynamoDB's scalability) as a queryable tension instead of deleting the first decision. That's what **RELATE > DELETE** means in practice.
+
+After a few sessions, try:
+- *"What's blocking our progress?"* surfaces blockers and their downstream impact
+- *"Why did we choose PostgreSQL originally?"* traces the full causal chain
+- *"What if we switch to DynamoDB?"* maps the downstream consequences
+
+After 20 sessions, you have a curated knowledge base of your project's decisions, not a pile of notes. Knowledge that stays relevant graduates through temporal tiers. One-off observations fade naturally.
+
+---
+
 ## Works With Your Stack
 
 Drop-in adapters that implement your framework's native interface. Same API you already use — plus `query.tensions()`.

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/README.md

@@ -19,19 +19,20 @@ llm = lambda prompt: (client.chat.completions.create(
 ).choices[0].message.content or "")
 
 with UnifiedMemory("agent-memory.json", embedder=OpenAIEmbeddings(), llm=llm) as mem:
-    mem.add("We chose Redis for session storage — sub-ms reads are critical for UX")
-    mem.add("Redis cluster costs are killing us at $200/mo for 3 nodes")
-    mem.add("Decided: switch to PostgreSQL — handles our scale at $15/mo")
+    mem.add("Redis gives sub-ms reads which is critical for our UX requirements")
+    mem.add("Redis clustering costs $200/month which exceeds our infrastructure budget of $50/month")
+    mem.add("PostgreSQL gives us rich queries at $15/month but read latency is 10-50ms")
 
-    print(mem.memory.query.tensions())
-    # → Tension: "sub-ms reads critical for UX" vs "cluster costs $200/mo"
-    #   axis: "performance vs cost"
+    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
 
-    print(mem.memory.query.blocked())
-    # → what's stuck and why, with downstream impact
+    blocked = mem.memory.query.blocked()
+    # → BlockedResult(0 blockers)
 
-    print(mem.memory.query.why(node_id))
-    # → full causal chain backward from any decision
+    why = mem.memory.query.why(node_id)
+    # → CausalAncestry: full chain backward from any node
 ```
 
 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*.
@@ -64,7 +65,9 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 pip install flowscript-agents
 ```
 
-Auto-detects your API key and configures the full stack — vector search, typed extraction, and contradiction handling. Also supports `ANTHROPIC_API_KEY`. 11 tools, zero additional setup.
+Auto-detects your API key and configures the full stack: vector search, typed extraction, and contradiction handling. Also supports `ANTHROPIC_API_KEY`. 13 reasoning tools.
+
+**Then add the [CLAUDE.md snippet](examples/CLAUDE.md.example) to your project.** This is what turns tools into a workflow. It tells your agent *when* to record decisions, surface tensions before new choices, and check blockers at session start. Without it, the tools are available but passive. With it, your agent proactively tracks your project's reasoning.
 
 ### Python SDK
 
@@ -91,6 +94,31 @@ FlowScript operates at three levels. Pick where you start:
 
 ---
 
+## First 5 Minutes
+
+With the MCP server running and the CLAUDE.md snippet in your project, try this conversation:
+
+> "I need to decide between PostgreSQL and MongoDB for our user data. We need ACID compliance for payments but flexibility for user profiles."
+
+Your agent stores the decision context, tradeoffs, and rationale automatically. Now introduce contradictory information:
+
+> "Actually, I've been looking at DynamoDB. The scale requirements might matter more than I thought."
+
+Now ask:
+
+> "What tensions do we have in our architecture decisions?"
+
+FlowScript preserved both perspectives (PostgreSQL's ACID compliance vs DynamoDB's scalability) as a queryable tension instead of deleting the first decision. That's what **RELATE > DELETE** means in practice.
+
+After a few sessions, try:
+- *"What's blocking our progress?"* surfaces blockers and their downstream impact
+- *"Why did we choose PostgreSQL originally?"* traces the full causal chain
+- *"What if we switch to DynamoDB?"* maps the downstream consequences
+
+After 20 sessions, you have a curated knowledge base of your project's decisions, not a pile of notes. Knowledge that stays relevant graduates through temporal tiers. One-off observations fade naturally.
+
+---
+
 ## Works With Your Stack
 
 Drop-in adapters that implement your framework's native interface. Same API you already use — plus `query.tensions()`.

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/docs/audit-trail.md

@@ -22,8 +22,10 @@ mem = Memory.load_or_create("agent-memory.json",
 
 ## Event Types
 
-### Python (13 events)
-`node_create`, `node_update`, `node_merge`, `node_remove`, `relationship_create`, `state_change`, `graduation`, `prune`, `session_start`, `session_end`, `session_wrap`, `consolidation`, `audit_cleanup`
+### Python (15 events)
+`node_create`, `update_node`, `update_node_merge`, `node_remove`, `relationship_create`, `state_change`, `graduation`, `prune`, `session_start`, `session_end`, `session_wrap`, `consolidation`, `transcript_extract`, `consolidation_batch`, `audit_cleanup`
+
+The `transcript_extract` event fires after each auto-extraction call with stats (nodes extracted/created/deduplicated, type breakdown, node IDs). The `consolidation_batch` event fires after consolidation with full metrics (contested/updated/related/resolved counts, collision stats, health status).
 
 ### TypeScript (14 events)
 `node_create`, `relationship_create`, `state_change`, `modifier_add`, `session_start`, `session_end`, `session_wrap`, `graduation`, `prune`, `snapshot`, `restore`, `transcript_extract`, `budget_apply`, `audit_cleanup`
@@ -70,6 +72,15 @@ result = Memory.query_audit("agent-memory.audit.jsonl",
 # → AuditQueryResult(entries=[...], total_scanned=42, files_searched=1)
 ```
 
+## MCP Audit Tools
+
+The Python MCP server exposes `query_audit` and `verify_audit` as tools (13 tools total). When configured with an `AuditConfig`, your agent can query and verify the audit trail through natural conversation:
+
+- **`query_audit`** filters by time range, event types, node ID, session ID, adapter, and limit. Supports optional chain verification.
+- **`verify_audit`** checks the full hash chain integrity and returns entry counts.
+
+Both handle missing audit files gracefully (returns `valid: null` for verify, empty results for query).
+
 ## SIEM Integration
 
 Stream audit events to Datadog, Splunk, or any monitoring system via the `on_event` callback:

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/audit.py

@@ -28,7 +28,7 @@ import sys
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Literal, Optional
 
 
 # =============================================================================
@@ -50,6 +50,10 @@ class AuditConfig:
             for testing or when tamper-evidence is not needed.
         verbosity: "standard" (default) = mutation events only. "full" =
             mutations + read/query access events (for HIPAA access auditing).
+        encryption: "none" (default) or "aes-256-gcm". Encryption at rest for
+            audit trail files. NOT YET IMPLEMENTED — v2 commitment for SOC2/
+            enterprise compliance. Setting to anything other than "none" raises
+            NotImplementedError.
         on_event: Optional callback invoked for every audit entry. Receives the
             full entry dict AFTER disk write. Callback failure never blocks
             audit persistence. Use for SIEM integration, Observatory, or custom
@@ -61,8 +65,16 @@ class AuditConfig:
     retention_months: Optional[int] = 84
     hash_chain: bool = True
     verbosity: str = "standard"
+    encryption: Literal["none", "aes-256-gcm"] = "none"
     on_event: Optional[Callable[[dict[str, Any]], None]] = None
 
+    def __post_init__(self) -> None:
+        if self.encryption != "none":
+            raise NotImplementedError(
+                f"Encryption at rest ('{self.encryption}') is not yet implemented. "
+                "This is a documented v2 commitment. Currently only 'none' is supported."
+            )
+
 
 # =============================================================================
 # Result Types
@@ -84,7 +96,7 @@ class AuditQueryResult:
 class AuditVerifyResult:
     """Result of verify_audit()."""
 
-    valid: bool
+    valid: Optional[bool]  # True = chain intact, False = chain broken, None = no audit trail found
     total_entries: int
     files_verified: int
     legacy_entries: int = 0
@@ -654,7 +666,7 @@ class AuditWriter:
             files_to_verify.append(active_path)
 
         if not files_to_verify:
-            return AuditVerifyResult(valid=True, total_entries=0, files_verified=0)
+            return AuditVerifyResult(valid=None, total_entries=0, files_verified=0)
 
         # Verify chain across all files
         total_entries = 0

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/camel_ai.py

@@ -131,6 +131,7 @@ class FlowScriptCamelMemory(_CamelAgentMemory):
         self._max_tokens = max_tokens
         self._agent_id: str | None = None
         self._memory.session_start()
+        self._memory.set_adapter_context("camel_ai", "FlowScriptCamelMemory", "init")
 
     @property
     def memory(self) -> Memory:
@@ -173,6 +174,7 @@ class FlowScriptCamelMemory(_CamelAgentMemory):
         Returns:
             List of ContextRecord objects scored for context assembly.
         """
+        self._memory.set_adapter_operation("retrieve")
         records: list[ContextRecord] = []
 
         # Order by tier priority
@@ -273,6 +275,7 @@ class FlowScriptCamelMemory(_CamelAgentMemory):
         Args:
             records: List of MemoryRecord-like objects.
         """
+        self._memory.set_adapter_operation("write_records")
         # Extract content from all records
         contents = []
         for record in records:
@@ -399,6 +402,7 @@ class FlowScriptCamelMemory(_CamelAgentMemory):
         Uses unified search (vector + keyword + temporal) when available,
         falls back to word-level matching.
         """
+        self._memory.set_adapter_operation("recall")
         if self._unified:
             unified_results = self._unified.search(query, top_k=limit)
             if unified_results:
@@ -452,9 +456,12 @@ class FlowScriptCamelMemory(_CamelAgentMemory):
 
     def close(self):
         """End session: prune dormant, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/crewai.py

@@ -101,6 +101,7 @@ class FlowScriptStorage:
         self._rebuild_index()
         # Start temporal session
         self._memory.session_start()
+        self._memory.set_adapter_context("crewai", "FlowScriptStorage", "init")
 
     @property
     def memory(self) -> Memory:
@@ -157,6 +158,7 @@ class FlowScriptStorage:
 
     def save(self, records: list[Any]) -> None:
         """Save MemoryRecord objects."""
+        self._memory.set_adapter_operation("save")
         for record in records:
             rec_id = getattr(record, "id", str(uuid.uuid4()))
             content = getattr(record, "content", str(record))
@@ -222,6 +224,7 @@ class FlowScriptStorage:
         for scoring (compares query_embedding against indexed node vectors).
         Falls back to per-record embeddings or content matching otherwise.
         """
+        self._memory.set_adapter_operation("search")
         results: list[tuple[_RecordEntry, float]] = []
 
         # Build vector scores from VectorIndex when available
@@ -486,9 +489,12 @@ class FlowScriptStorage:
 
     def close(self):
         """End the session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/embeddings/extract.py

@@ -581,7 +581,7 @@ class AutoExtract:
         rels_created = self._create_extraction_relationships(extraction, node_refs)
         states_created = self._apply_extraction_states(extraction, node_refs)
 
-        return IngestResult(
+        result = IngestResult(
             nodes_created=created,
             nodes_deduplicated=deduped,
             relationships_created=rels_created,
@@ -589,6 +589,14 @@ class AutoExtract:
             node_ids=[ref.id for ref in node_refs],
         )
 
+        # Audit: extraction provenance (never crash ingest for audit failures)
+        try:
+            self._write_extraction_audit(extraction, result)
+        except Exception:
+            print("AutoExtract: audit write failed (transcript_extract)", file=sys.stderr)
+
+        return result
+
     def _ingest_with_consolidation(
         self,
         extraction: ExtractionResult,
@@ -636,7 +644,7 @@ class AutoExtract:
                 if action.target_node_id not in surviving_ids:
                     surviving_ids.append(action.target_node_id)
 
-        return IngestResult(
+        result = IngestResult(
             nodes_created=consolidation_result.nodes_added,
             nodes_deduplicated=consolidation_result.nodes_skipped,
             relationships_created=rels_created + consolidation_result.nodes_related + consolidation_result.nodes_resolved,
@@ -651,6 +659,20 @@ class AutoExtract:
             fallback_count=consolidation_result.fallback_count,
         )
 
+        # Audit: extraction provenance (never crash ingest for audit failures)
+        try:
+            self._write_extraction_audit(extraction, result)
+        except Exception:
+            print("AutoExtract: audit write failed (transcript_extract)", file=sys.stderr)
+
+        # Audit: consolidation batch summary
+        try:
+            self._write_consolidation_batch_audit(consolidation_result)
+        except Exception:
+            print("AutoExtract: audit write failed (consolidation_batch)", file=sys.stderr)
+
+        return result
+
     # -------------------------------------------------------------------------
     # Shared helpers
     # -------------------------------------------------------------------------
@@ -775,6 +797,50 @@ class AutoExtract:
 
         return self.ingest(transcript, metadata=metadata, actor=actor)
 
+    def _write_extraction_audit(
+        self,
+        extraction: ExtractionResult,
+        result: IngestResult,
+    ) -> None:
+        """Write a transcript_extract audit event summarizing what was extracted."""
+        # Build type breakdown from extraction
+        type_counts: dict[str, int] = {}
+        for node in extraction.nodes:
+            t = node.type if node.type in _VALID_NODE_TYPES else "thought"
+            type_counts[t] = type_counts.get(t, 0) + 1
+
+        self._memory.write_audit("transcript_extract", {
+            "nodes_extracted": len(extraction.nodes),
+            "nodes_created": result.nodes_created,
+            "nodes_deduplicated": result.nodes_deduplicated,
+            "relationships_extracted": len(extraction.relationships),
+            "relationships_created": result.relationships_created,
+            "states_created": result.states_created,
+            "type_breakdown": type_counts,
+            "node_ids": result.node_ids,
+            "consolidation_used": result.consolidation_used,
+        })
+
+    def _write_consolidation_batch_audit(
+        self,
+        consolidation_result: Any,
+    ) -> None:
+        """Write a consolidation_batch audit event summarizing batch results."""
+        self._memory.write_audit("consolidation_batch", {
+            "nodes_added": consolidation_result.nodes_added,
+            "nodes_updated": consolidation_result.nodes_updated,
+            "nodes_related": consolidation_result.nodes_related,
+            "nodes_resolved": consolidation_result.nodes_resolved,
+            "nodes_skipped": consolidation_result.nodes_skipped,
+            "nodes_novel": consolidation_result.nodes_novel,
+            "collision_count": consolidation_result.collision_count,
+            "collisions_retried": consolidation_result.collisions_retried,
+            "error_count": consolidation_result.error_count,
+            "total_contested": consolidation_result.total_contested,
+            "llm_calls": consolidation_result.llm_calls,
+            "health_ok": consolidation_result.health_ok,
+        })
+
     def _get_node_creator(self, type_str: str) -> Callable[[str], NodeRef]:
         """Get the Memory node creation method for a type string.
 

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/google_adk.py

@@ -90,6 +90,7 @@ class FlowScriptMemoryService(_ADKBaseMemoryService):
         self._file_path = file_path
         # Start temporal session
         self._memory.session_start()
+        self._memory.set_adapter_context("google_adk", "FlowScriptMemoryService", "init")
 
     @property
     def memory(self) -> Memory:
@@ -128,6 +129,7 @@ class FlowScriptMemoryService(_ADKBaseMemoryService):
         to create typed reasoning nodes from session content. Otherwise,
         stores raw content as thought nodes.
         """
+        self._memory.set_adapter_operation("add_session")
         app_name = getattr(session, "app_name", "unknown")
         user_id = getattr(session, "user_id", "unknown")
         session_id = getattr(session, "id", "unknown")
@@ -206,6 +208,7 @@ class FlowScriptMemoryService(_ADKBaseMemoryService):
 
         Returns ADK SearchMemoryResponse with MemoryEntry objects.
         """
+        self._memory.set_adapter_operation("search_memory")
         # Use unified search when available (vector + keyword + temporal)
         if self._unified:
             unified_results = self._unified.search(query, top_k=10)
@@ -321,6 +324,7 @@ class FlowScriptMemoryService(_ADKBaseMemoryService):
         custom_metadata: Mapping[str, object] | None = None,
     ) -> None:
         """Incremental event addition."""
+        self._memory.set_adapter_operation("add_events")
         prev_ref = None
         for event in events:
             content = _extract_event_content(event)
@@ -356,9 +360,12 @@ class FlowScriptMemoryService(_ADKBaseMemoryService):
 
     def close(self):
         """End the session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/haystack.py

@@ -101,6 +101,7 @@ class FlowScriptMemoryStore:
         self._id_map: dict[str, str] = {}
         self._rebuild_index()
         self._memory.session_start()
+        self._memory.set_adapter_context("haystack", "FlowScriptMemoryStore", "init")
 
     @property
     def memory(self) -> Memory:
@@ -158,6 +159,7 @@ class FlowScriptMemoryStore:
             user_id: Optional user identifier for scoping.
             **kwargs: Additional args (agent_id, run_id, etc.)
         """
+        self._memory.set_adapter_operation("add_memories")
         haystack_meta = {"haystack_user_id": user_id}
         for k, v in kwargs.items():
             haystack_meta[f"haystack_{k}"] = v
@@ -245,6 +247,7 @@ class FlowScriptMemoryStore:
         Returns:
             List of ChatMessage-compatible dicts with memory content.
         """
+        self._memory.set_adapter_operation("search_memories")
         # Use unified search when available (vector + keyword + temporal)
         scored: list[tuple[NodeRef, float]] = []
         if query and self._unified:
@@ -392,9 +395,12 @@ class FlowScriptMemoryStore:
 
     def close(self):
         """End session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/langgraph.py

@@ -124,6 +124,7 @@ class FlowScriptStore(BaseStore):
         self._rebuild_index()
         # Start temporal session (resets touch dedup)
         self._memory.session_start()
+        self._memory.set_adapter_context("langgraph", "FlowScriptStore", "init")
 
     @property
     def memory(self) -> Memory:
@@ -204,6 +205,7 @@ class FlowScriptStore(BaseStore):
         return self.batch(ops)
 
     def _handle_get(self, op: GetOp) -> Item | None:
+        self._memory.set_adapter_operation("get")
         stored = self._items.get((op.namespace, op.key))
         if stored is None:
             return None
@@ -218,6 +220,7 @@ class FlowScriptStore(BaseStore):
         )
 
     def _handle_put(self, op: PutOp) -> None:
+        self._memory.set_adapter_operation("put")
         ns = op.namespace
         key = op.key
 
@@ -381,9 +384,12 @@ class FlowScriptStore(BaseStore):
 
     def close(self):
         """End the session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/llamaindex.py

@@ -148,6 +148,7 @@ class FlowScriptMemoryBlock(BaseMemoryBlock[str]):
             else:
                 self._memory = Memory(options=options)
         self._memory.session_start()
+        self._memory.set_adapter_context("llamaindex", "FlowScriptMemoryBlock", "init")
 
     @property
     def memory(self) -> Memory:
@@ -337,6 +338,7 @@ class FlowScriptMemoryBlock(BaseMemoryBlock[str]):
 
     def store(self, content: str, **metadata: Any) -> NodeRef:
         """Store a thought directly. Returns NodeRef for chaining."""
+        self._memory.set_adapter_operation("store")
         ref = self._memory.thought(content)
         if metadata:
             ref.node.ext = ref.node.ext or {}
@@ -348,6 +350,7 @@ class FlowScriptMemoryBlock(BaseMemoryBlock[str]):
 
         Uses unified search (vector + keyword + temporal) when available.
         """
+        self._memory.set_adapter_operation("recall")
         if self._unified:
             unified_results = self._unified.search(query, top_k=limit)
             if unified_results:
@@ -401,9 +404,12 @@ class FlowScriptMemoryBlock(BaseMemoryBlock[str]):
 
     def close(self):
         """End session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/mcp.py

@@ -32,15 +32,20 @@ When OPENAI_API_KEY is set, the server auto-configures:
 - LLM extraction (gpt-4o-mini) for typed reasoning extraction
 - Consolidation (gpt-4o-mini) for memory management (UPDATE/RELATE/RESOLVE)
 
-Tools exposed:
+Tools exposed (13):
 - search_memory: Unified search (vector + keyword + temporal)
 - add_memory: Auto-extract reasoning from text with consolidation
 - get_context: Get formatted memory for prompt injection
 - query_tensions: Find all tensions/tradeoffs in memory
 - query_blocked: Find all blocked items with impact analysis
 - query_why: Trace causal chain for a node
+- query_what_if: Trace downstream impact
 - query_alternatives: Reconstruct decision from options
+- remove_memory: Remove a node from memory
+- session_wrap: End-of-session lifecycle (graduation, pruning, save)
 - memory_stats: Get memory statistics
+- query_audit: Search the audit trail with filters
+- verify_audit: Verify hash chain integrity
 """
 
 from __future__ import annotations
@@ -266,6 +271,50 @@ TOOLS = [
         ),
         "inputSchema": {"type": "object", "properties": {}},
     },
+    {
+        "name": "query_audit",
+        "description": (
+            "Search the audit trail for reasoning provenance. Call this to understand "
+            "how memory evolved — what was extracted, what consolidation decided, "
+            "which adapter made changes, or what happened in a specific session. "
+            "Returns hash-chained audit entries matching the filters."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "after": {"type": "string", "description": "Only entries after this ISO timestamp"},
+                "before": {"type": "string", "description": "Only entries before this ISO timestamp"},
+                "events": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Filter by event types. Available: node_create, relationship_create, "
+                        "state_change, graduation, prune, session_start, session_end, "
+                        "session_wrap, consolidation, consolidation_batch, transcript_extract, "
+                        "node_remove, update_node, update_node_merge, audit_cleanup"
+                    ),
+                },
+                "node_id": {"type": "string", "description": "Filter by node involvement"},
+                "session_id": {"type": "string", "description": "Filter by session ID"},
+                "adapter": {"type": "string", "description": "Filter by adapter framework name"},
+                "limit": {"type": "integer", "description": "Maximum entries (default 100)", "default": 100},
+                "verify_chain": {
+                    "type": "boolean",
+                    "description": "Also verify hash chain integrity of matched entries",
+                    "default": False,
+                },
+            },
+        },
+    },
+    {
+        "name": "verify_audit",
+        "description": (
+            "Verify hash chain integrity of the entire audit trail. Call this to "
+            "confirm the audit trail has not been tampered with. Returns chain "
+            "validity status, total entries verified, and location of any break."
+        ),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
 ]
 
 
@@ -293,6 +342,8 @@ class MCPHandler:
             "remove_memory": self._remove_memory,
             "session_wrap": self._session_wrap,
             "memory_stats": self._memory_stats,
+            "query_audit": self._query_audit,
+            "verify_audit": self._verify_audit,
         }
         handler = handlers.get(name)
         if handler is None:
@@ -467,6 +518,69 @@ class MCPHandler:
         return stats
 
 
+    def _get_audit_path(self) -> str | None:
+        """Derive audit trail path from memory file path."""
+        mem_path = self._umem.memory._file_path
+        if not mem_path:
+            return None
+        from pathlib import Path as _P
+        return str(_P(mem_path).parent / (_P(mem_path).stem + ".audit.jsonl"))
+
+    def _query_audit(self, args: dict) -> dict:
+        audit_path = self._get_audit_path()
+        if not audit_path:
+            return {"error": "No memory file path — audit trail requires file-based persistence"}
+        try:
+            result = Memory.query_audit(
+                audit_path,
+                after=args.get("after"),
+                before=args.get("before"),
+                events=args.get("events"),
+                node_id=args.get("node_id"),
+                session_id=args.get("session_id"),
+                adapter=args.get("adapter"),
+                limit=args.get("limit", 100),
+                verify_chain=args.get("verify_chain", False),
+            )
+            resp: dict[str, Any] = {
+                "entries": result.entries,
+                "total_scanned": result.total_scanned,
+                "files_searched": result.files_searched,
+                "count": len(result.entries),
+            }
+            if result.chain_valid is not None:
+                resp["chain_valid"] = result.chain_valid
+                if result.chain_break_at is not None:
+                    resp["chain_break_at"] = result.chain_break_at
+            return resp
+        except FileNotFoundError:
+            return {"entries": [], "total_scanned": 0, "files_searched": 0, "count": 0,
+                    "note": "No audit trail file found — audit may not be configured"}
+
+    def _verify_audit(self, args: dict) -> dict:
+        audit_path = self._get_audit_path()
+        if not audit_path:
+            return {"error": "No memory file path — audit trail requires file-based persistence"}
+        try:
+            result = Memory.verify_audit(audit_path)
+            resp: dict[str, Any] = {
+                "valid": result.valid,
+                "total_entries": result.total_entries,
+                "files_verified": result.files_verified,
+                "legacy_entries": result.legacy_entries,
+            }
+            if result.valid is False:
+                if result.chain_break_at is not None:
+                    resp["chain_break_at"] = result.chain_break_at
+                if result.chain_break_file is not None:
+                    resp["chain_break_file"] = result.chain_break_file
+            return resp
+        except FileNotFoundError:
+            return {"valid": None, "total_entries": 0, "files_verified": 0,
+                    "status": "no_audit_trail",
+                    "note": "No audit trail file found — auditing may not be configured"}
+
+
 def _serialize_query_result(result: Any, _seen: set | None = None) -> dict:
     """Best-effort serialization of query result dataclasses."""
     if _seen is None:
@@ -711,6 +825,7 @@ def run_server(
     # Start session tracking — enables touch deduplication and temporal
     # intelligence across the lifetime of this MCP server instance.
     umem.memory.session_start()
+    umem.memory.set_adapter_context("mcp", "FlowScriptMCP", "server")
     handler = MCPHandler(umem)
 
     try:
@@ -778,10 +893,12 @@ def run_server(
     finally:
         # Safety net: save state when stdin closes (Claude Code exits).
         # Use save() not close() — don't prune on unclean shutdown.
+        # Order: save first (may write audit entries), then clear context.
         try:
             umem.save()
         except Exception:
             pass
+        umem.memory.clear_adapter_context()
 
 
 # =============================================================================

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/memory.py

@@ -376,6 +376,15 @@ class Memory:
             "operation": operation,
         }
 
+    def set_adapter_operation(self, operation: str) -> None:
+        """Update the operation field of existing adapter context.
+
+        Use this for per-operation attribution without resetting framework/class.
+        No-op if no adapter context is set.
+        """
+        if self._adapter_context is not None:
+            self._adapter_context["operation"] = operation
+
     def clear_adapter_context(self) -> None:
         """Clear adapter attribution."""
         self._adapter_context = None
@@ -1357,8 +1366,13 @@ class Memory:
                 deduped_states.append(state)
         self._states = deduped_states
 
-    def _write_audit(self, event: str, data: dict[str, Any]) -> None:
-        """Write an audit trail entry via AuditWriter (hash-chained, rotatable)."""
+    def write_audit(self, event: str, data: dict[str, Any]) -> None:
+        """Write an audit trail entry via AuditWriter (hash-chained, rotatable).
+
+        Public API for audit event emission. Used by Memory internals and
+        by cross-module callers (AutoExtract, ConsolidationEngine) that need
+        to record provenance events in the same hash chain.
+        """
         writer = self._ensure_audit_writer()
         if writer is None:
             return
@@ -1369,6 +1383,9 @@ class Memory:
             adapter=self._adapter_context,
         )
 
+    # Backwards compat alias — internal callers use this, will migrate over time
+    _write_audit = write_audit
+
     def _merge_temporal(self, old_id: str, target_id: str) -> None:
         """Merge temporal metadata from old node into target — preserve the richer history.
 

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/openai_agents.py

@@ -106,6 +106,7 @@ class FlowScriptSession:
         self._rebuild_items()
         # Start temporal session
         self._memory.session_start()
+        self._memory.set_adapter_context("openai_agents", "FlowScriptSession", "init")
 
     @property
     def memory(self) -> Memory:
@@ -148,6 +149,7 @@ class FlowScriptSession:
 
     async def get_items(self, limit: int | None = None) -> list[dict[str, Any]]:
         """Get conversation items, optionally limited."""
+        self._memory.set_adapter_operation("get_items")
         items = self._items[-limit:] if limit is not None else self._items
         # Touch retrieved nodes — retrieval is engagement
         touched_ids = []
@@ -161,6 +163,7 @@ class FlowScriptSession:
 
     async def add_items(self, items: list[dict[str, Any]]) -> None:
         """Add conversation items to the session."""
+        self._memory.set_adapter_operation("add_items")
         base_order = len(self._items)
         for i, item in enumerate(items):
             content = _extract_item_content(item)
@@ -242,9 +245,12 @@ class FlowScriptSession:
 
     def close(self):
         """End the session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/pydantic_ai.py

@@ -98,6 +98,7 @@ class FlowScriptDeps:
             else:
                 self._memory = Memory(options=self.options)
         self._memory.session_start()
+        self._memory.set_adapter_context("pydantic_ai", "FlowScriptDeps", "init")
 
     @property
     def memory(self) -> Memory:
@@ -141,6 +142,7 @@ class FlowScriptDeps:
         Returns:
             NodeRef for building relationships (causes, tension_with, etc.)
         """
+        self._memory.set_adapter_operation("store")
         if self._unified and self._unified.extractor:
             result = self._unified.add(content, metadata=metadata if metadata else None)
             # Return first extracted node for chaining
@@ -175,6 +177,7 @@ class FlowScriptDeps:
         Returns:
             List of dicts with 'content', 'id', 'tier', 'frequency' keys.
         """
+        self._memory.set_adapter_operation("recall")
         # Use unified search when available (vector + keyword + temporal)
         if self._unified:
             unified_results = self._unified.search(query, top_k=limit)
@@ -256,9 +259,12 @@ class FlowScriptDeps:
 
     def close(self):
         """End session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/flowscript_agents/smolagents.py

@@ -91,6 +91,7 @@ class FlowScriptMemoryTools:
                 self._memory = Memory(options=options)
         self._file_path = file_path
         self._memory.session_start()
+        self._memory.set_adapter_context("smolagents", "FlowScriptMemoryTools", "init")
 
     @property
     def memory(self) -> Memory:
@@ -139,9 +140,12 @@ class FlowScriptMemoryTools:
 
     def close(self):
         """End session: prune dormant nodes, save. Returns SessionWrapResult."""
-        if self._unified:
-            return self._unified.close()
-        return self._memory.session_wrap()
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
 
     def __enter__(self):
         return self
@@ -196,6 +200,7 @@ class _StoreMemoryTool(_BaseFSTool):
     output_type = "string"
 
     def forward(self, content: str, category: str = "observation") -> str:
+        self._memory.set_adapter_operation("store")
         # Use auto-extraction when available
         if self._unified and self._unified.extractor:
             result = self._unified.add(content, metadata={"category": category})
@@ -232,6 +237,7 @@ class _RecallMemoryTool(_BaseFSTool):
     output_type = "string"
 
     def forward(self, query: str, limit: int = 5) -> str:
+        self._memory.set_adapter_operation("recall")
         # Use unified search when available (vector + keyword + temporal)
         if self._unified:
             unified_results = self._unified.search(query, top_k=limit)

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowscript-agents"
-version = "0.2.0"
+version = "0.2.1"
 description = "Complete agent memory: reasoning queries + vector search + auto-extraction. Decision intelligence for LangGraph, CrewAI, Google ADK, OpenAI Agents SDK, Pydantic AI, smolagents, LlamaIndex, Haystack, CAMEL-AI, and Vercel AI SDK."
 readme = "README.md"
 license = "MIT"

{flowscript_agents-0.2.0 → flowscript_agents-0.2.1}/tests/test_mcp.py

@@ -31,7 +31,7 @@ class TestToolDefinitions:
             assert "inputSchema" in tool
 
     def test_tool_count(self):
-        assert len(TOOLS) == 11
+        assert len(TOOLS) == 13
 
     def test_tool_names(self):
         names = {t["name"] for t in TOOLS}
@@ -40,6 +40,7 @@ class TestToolDefinitions:
             "query_tensions", "query_blocked", "query_why",
             "query_what_if", "query_alternatives",
             "remove_memory", "session_wrap", "memory_stats",
+            "query_audit", "verify_audit",
         }
         assert names == expected
 
@@ -294,7 +295,7 @@ class TestMCPStdioProtocol:
             "jsonrpc": "2.0", "id": 2, "method": "tools/list",
         })
         tools = resp["result"]["tools"]
-        assert len(tools) == 11
+        assert len(tools) == 13
         names = {t["name"] for t in tools}
         assert "search_memory" in names
         assert "query_what_if" in names