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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowscript-agents
-Version: 0.2.0
+Version: 0.2.2
 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*.
@@ -110,6 +111,16 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 
 ### MCP Server (Claude Code / Cursor — zero code)
 
+```bash
+pip install flowscript-agents openai
+```
+
+The `openai` package is required for extraction, consolidation, and vector search. Without it, `add_memory` stores raw text and `query_tensions` won't find anything.
+
+Add to your editor's MCP config:
+
+**Claude Code** — add to `.claude/settings.json` in your project (or `~/.claude/settings.json` for global):
+
 ```json
 {
   "mcpServers": {
@@ -124,11 +135,63 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 }
 ```
 
+**Cursor / Windsurf / VS Code** — add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "flowscript": {
+      "type": "stdio",
+      "command": "flowscript-mcp",
+      "args": ["--memory", "./project-memory.json"],
+      "env": {
+        "OPENAI_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+**Fallback:** If `env` passthrough doesn't work in your editor, export the key in your shell before launching:
 ```bash
-pip install flowscript-agents
+export OPENAI_API_KEY=your-key
 ```
 
-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.
+The server auto-detects your API key and configures the full stack:
+
+| Key | What you get |
+|:----|:-------------|
+| `OPENAI_API_KEY` | Vector search (text-embedding-3-small) + typed extraction (gpt-4o-mini) + consolidation |
+| `ANTHROPIC_API_KEY` | Typed extraction + consolidation (no embeddings, keyword search fallback) |
+| Neither | Raw text storage only. Tools work, but no typed extraction and `query_tensions` won't find anything. |
+
+**Without an API key, you get a degraded experience.** The server warns on startup and in tool responses.
+
+### Embedding Providers
+
+The default is OpenAI `text-embedding-3-small`. To use a different provider, pass flags in `args`:
+
+```json
+"args": ["--memory", "./project-memory.json", "--embedder", "ollama", "--embedding-model", "nomic-embed-text"]
+```
+
+| Flag | What it does | Default |
+|:-----|:-------------|:--------|
+| `--embedder` | Embedding provider: `openai`, `sentence-transformers`, or `ollama` | Auto-detected from API key |
+| `--embedding-model` | Model name (provider-specific) | `text-embedding-3-small` (OpenAI) |
+| `--llm-model` | LLM for extraction and consolidation | `gpt-4o-mini` |
+| `--no-auto` | Disable auto-configuration from API keys | Off |
+
+**Local embeddings (free, no API key for embeddings):**
+
+| Provider | Install | Example model | Notes |
+|:---------|:--------|:--------------|:------|
+| Ollama | [Install Ollama](https://ollama.com), then `ollama pull nomic-embed-text` | `nomic-embed-text` | Beats text-embedding-3-small. 274MB. |
+| SentenceTransformers | `pip install sentence-transformers` | `BAAI/bge-m3` | Runs on CPU. Downloads on first use. |
+
+You still need an LLM API key (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) for typed extraction and consolidation, even when using local embeddings.
+
+**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 +218,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()`.
@@ -261,7 +349,7 @@ Under the hood: a local semantic graph with typed nodes, typed relationships, an
 
 | Package | What | Install |
 |:--------|:-----|:--------|
-| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, unified memory, consolidation, audit trail | `pip install flowscript-agents` |
+| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, unified memory, consolidation, audit trail | `pip install flowscript-agents openai` |
 | [flowscript-core](https://www.npmjs.com/package/flowscript-core) | TypeScript SDK — Memory class, 15 tools, token budgeting, audit trail | `npm install flowscript-core` |
 | [flowscript.org](https://flowscript.org) | Web editor, D3 visualization, live query panel | Browser |
 

{flowscript_agents-0.2.0 → flowscript_agents-0.2.2}/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*.
@@ -46,6 +47,16 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 
 ### MCP Server (Claude Code / Cursor — zero code)
 
+```bash
+pip install flowscript-agents openai
+```
+
+The `openai` package is required for extraction, consolidation, and vector search. Without it, `add_memory` stores raw text and `query_tensions` won't find anything.
+
+Add to your editor's MCP config:
+
+**Claude Code** — add to `.claude/settings.json` in your project (or `~/.claude/settings.json` for global):
+
 ```json
 {
   "mcpServers": {
@@ -60,11 +71,63 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 }
 ```
 
+**Cursor / Windsurf / VS Code** — add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "flowscript": {
+      "type": "stdio",
+      "command": "flowscript-mcp",
+      "args": ["--memory", "./project-memory.json"],
+      "env": {
+        "OPENAI_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+**Fallback:** If `env` passthrough doesn't work in your editor, export the key in your shell before launching:
 ```bash
-pip install flowscript-agents
+export OPENAI_API_KEY=your-key
 ```
 
-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.
+The server auto-detects your API key and configures the full stack:
+
+| Key | What you get |
+|:----|:-------------|
+| `OPENAI_API_KEY` | Vector search (text-embedding-3-small) + typed extraction (gpt-4o-mini) + consolidation |
+| `ANTHROPIC_API_KEY` | Typed extraction + consolidation (no embeddings, keyword search fallback) |
+| Neither | Raw text storage only. Tools work, but no typed extraction and `query_tensions` won't find anything. |
+
+**Without an API key, you get a degraded experience.** The server warns on startup and in tool responses.
+
+### Embedding Providers
+
+The default is OpenAI `text-embedding-3-small`. To use a different provider, pass flags in `args`:
+
+```json
+"args": ["--memory", "./project-memory.json", "--embedder", "ollama", "--embedding-model", "nomic-embed-text"]
+```
+
+| Flag | What it does | Default |
+|:-----|:-------------|:--------|
+| `--embedder` | Embedding provider: `openai`, `sentence-transformers`, or `ollama` | Auto-detected from API key |
+| `--embedding-model` | Model name (provider-specific) | `text-embedding-3-small` (OpenAI) |
+| `--llm-model` | LLM for extraction and consolidation | `gpt-4o-mini` |
+| `--no-auto` | Disable auto-configuration from API keys | Off |
+
+**Local embeddings (free, no API key for embeddings):**
+
+| Provider | Install | Example model | Notes |
+|:---------|:--------|:--------------|:------|
+| Ollama | [Install Ollama](https://ollama.com), then `ollama pull nomic-embed-text` | `nomic-embed-text` | Beats text-embedding-3-small. 274MB. |
+| SentenceTransformers | `pip install sentence-transformers` | `BAAI/bge-m3` | Runs on CPU. Downloads on first use. |
+
+You still need an LLM API key (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`) for typed extraction and consolidation, even when using local embeddings.
+
+**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 +154,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()`.
@@ -197,7 +285,7 @@ Under the hood: a local semantic graph with typed nodes, typed relationships, an
 
 | Package | What | Install |
 |:--------|:-----|:--------|
-| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, unified memory, consolidation, audit trail | `pip install flowscript-agents` |
+| [flowscript-agents](https://pypi.org/project/flowscript-agents/) | Python SDK — 9 adapters, unified memory, consolidation, audit trail | `pip install flowscript-agents openai` |
 | [flowscript-core](https://www.npmjs.com/package/flowscript-core) | TypeScript SDK — Memory class, 15 tools, token budgeting, audit trail | `npm install flowscript-core` |
 | [flowscript.org](https://flowscript.org) | Web editor, D3 visualization, live query panel | Browser |
 

{flowscript_agents-0.2.0 → flowscript_agents-0.2.2}/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.2}/examples/CLAUDE.md.example

@@ -2,7 +2,8 @@
 #
 # Paste the section below into your project's CLAUDE.md to enable
 # proactive reasoning memory. FlowScript MCP tools are available
-# when the server is configured via .mcp.json or ~/.claude.json.
+# when the server is configured in your editor's MCP settings
+# (.claude/settings.json for Claude Code, .mcp.json for Cursor/Windsurf).
 
 ## Reasoning Memory (FlowScript)
 

{flowscript_agents-0.2.0 → flowscript_agents-0.2.2}/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.2}/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.2}/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.2}/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.2}/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