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

flowscript_agents-0.2.6/:memory:

@@ -0,0 +1,29 @@
+{
+  "flowscript_memory": "1.0.0",
+  "ir": {
+    "version": "1.0.0",
+    "nodes": [],
+    "relationships": [],
+    "states": [],
+    "invariants": {
+      "causal_acyclic": true,
+      "all_nodes_reachable": true,
+      "tension_axes_labeled": true,
+      "state_fields_present": true
+    },
+    "metadata": {
+      "source_files": [
+        "memory-api"
+      ],
+      "parsed_at": "2026-03-24T15:40:53.676226+00:00",
+      "parser": "flowscript-agents"
+    }
+  },
+  "temporal": {},
+  "config": {
+    "touch_on_query": true,
+    "source_file": null,
+    "author": null,
+    "temporal": null
+  }
+}

flowscript_agents-0.2.6/:memory:.audit.manifest.json

@@ -0,0 +1,10 @@
+{
+  "active_file": ":memory:.audit.jsonl",
+  "active_last_hash": "sha256:8dfb8c37838e7812e9c2727d8fe76ffca44f677b9d5499fa13513fac3800816f",
+  "active_last_seq": 0,
+  "files": [],
+  "last_cleanup": null,
+  "memory_file": ":memory:",
+  "retention_months": 84,
+  "version": 1
+}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowscript-agents
-Version: 0.2.4
+Version: 0.2.6
 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
@@ -70,7 +70,7 @@ Description-Content-Type: text/markdown
 
 <p align="center"><strong>Agent memory that tracks why you decided, what conflicts, and what's blocked. Not just what was said.</strong></p>
 
-[![Tests](https://img.shields.io/badge/tests-581%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/)
+[![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/)
 
 ---
 
@@ -341,11 +341,51 @@ Framework attribution is automatic — every audit entry records which adapter t
 
 ---
 
-## Memory That Evolves
+## Session Lifecycle — How Memory Gets Smarter
 
-Nodes graduate through four temporal tiers based on actual use — `current` → `developing` → `proven` → `foundation`. Every query touches returned nodes, so knowledge that keeps getting queried earns its place. One-off observations fade naturally. Dormant nodes are pruned to the audit trail — archived with full provenance, never destroyed.
+Just like a mind needs sleep to consolidate memories, your agent's reasoning graph needs regular session wraps to develop intelligence over time. Without consolidation cycles, knowledge accumulates as noise instead of maturing.
 
-After 20 sessions, your memory is a curated knowledge base, not a pile of notes. [Session lifecycle details →](docs/lifecycle.md)
+**Temporal tiers** — nodes graduate based on actual use:
+
+| Tier | Meaning | Behavior |
+|:-----|:--------|:---------|
+| `current` | Recent observations | May be pruned if not reinforced |
+| `developing` | Emerging patterns (2+ touches) | Building confidence |
+| `proven` | Validated through use (3+ touches) | Protected from pruning |
+| `foundation` | Core truths | Always preserved |
+
+Every query touches returned nodes — knowledge that keeps getting queried earns its place. One-off observations fade naturally. Dormant nodes are pruned to the audit trail — archived with full provenance, never destroyed.
+
+**Three ways session wraps happen:**
+
+1. **Explicit** — the LLM calls the `session_wrap` tool when you say "let's wrap up" (best results)
+2. **Auto-wrap** — after 5 minutes of inactivity, the MCP server auto-consolidates (safety net, configurable via `FLOWSCRIPT_AUTO_WRAP_MINUTES`, set to `0` to disable)
+3. **Process exit** — when the MCP server shuts down, a final consolidation runs automatically
+
+**For SDK users** — adapters support context managers that auto-wrap:
+
+```python
+from flowscript_agents.adapters.langgraph import FlowScriptStore
+
+with FlowScriptStore("agent-memory.json") as store:
+    # work happens — all mutations auto-save
+    store.put(("agents",), "key", {"value": "data"})
+# close() fires automatically → session_wrap() + save
+```
+
+After 20 sessions, your memory is a curated knowledge base, not a pile of notes. [Full lifecycle details →](docs/lifecycle.md)
+
+---
+
+## Description Integrity
+
+MCP tool descriptions are the prompts your LLM reads. If they're mutated in-process, the LLM silently follows poisoned instructions. The FlowScript MCP server includes three-layer integrity verification — a reference implementation of [deterministic description integrity for MCP](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2402):
+
+1. **`verify_integrity` tool** — LLM-callable. SHA-256 hashes of all tool definitions, deep-frozen at startup (`MappingProxyType`). Detects in-process mutation by malicious dependencies, monkey-patching, or middleware.
+2. **`flowscript://integrity/manifest` resource** — Host-verifiable. Claude Code / Cursor can verify descriptions without LLM involvement.
+3. **`tool-integrity.json`** — Build-time root of trust. Generated via `flowscript-mcp --generate-manifest`, ships in the package.
+
+Both the Python and [TypeScript](https://www.npmjs.com/package/flowscript-core) MCP servers implement this architecture. Honest threat model: detects in-process mutation, not supply chain or transport-layer attacks. [Full discussion →](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2402)
 
 ---
 
@@ -375,7 +415,7 @@ Under the hood: a local semantic graph with typed nodes, typed relationships, an
 | [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 |
 
-**1,312 tests** across Python (581) and TypeScript (731). Same audit trail format and canonical JSON serialization across both languages.
+**1,315 tests** across Python (584) and TypeScript (731). Same audit trail format and canonical JSON serialization across both languages.
 
 ### Docs
 

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

@@ -6,7 +6,7 @@
 
 <p align="center"><strong>Agent memory that tracks why you decided, what conflicts, and what's blocked. Not just what was said.</strong></p>
 
-[![Tests](https://img.shields.io/badge/tests-581%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/)
+[![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/)
 
 ---
 
@@ -277,11 +277,51 @@ Framework attribution is automatic — every audit entry records which adapter t
 
 ---
 
-## Memory That Evolves
+## Session Lifecycle — How Memory Gets Smarter
 
-Nodes graduate through four temporal tiers based on actual use — `current` → `developing` → `proven` → `foundation`. Every query touches returned nodes, so knowledge that keeps getting queried earns its place. One-off observations fade naturally. Dormant nodes are pruned to the audit trail — archived with full provenance, never destroyed.
+Just like a mind needs sleep to consolidate memories, your agent's reasoning graph needs regular session wraps to develop intelligence over time. Without consolidation cycles, knowledge accumulates as noise instead of maturing.
 
-After 20 sessions, your memory is a curated knowledge base, not a pile of notes. [Session lifecycle details →](docs/lifecycle.md)
+**Temporal tiers** — nodes graduate based on actual use:
+
+| Tier | Meaning | Behavior |
+|:-----|:--------|:---------|
+| `current` | Recent observations | May be pruned if not reinforced |
+| `developing` | Emerging patterns (2+ touches) | Building confidence |
+| `proven` | Validated through use (3+ touches) | Protected from pruning |
+| `foundation` | Core truths | Always preserved |
+
+Every query touches returned nodes — knowledge that keeps getting queried earns its place. One-off observations fade naturally. Dormant nodes are pruned to the audit trail — archived with full provenance, never destroyed.
+
+**Three ways session wraps happen:**
+
+1. **Explicit** — the LLM calls the `session_wrap` tool when you say "let's wrap up" (best results)
+2. **Auto-wrap** — after 5 minutes of inactivity, the MCP server auto-consolidates (safety net, configurable via `FLOWSCRIPT_AUTO_WRAP_MINUTES`, set to `0` to disable)
+3. **Process exit** — when the MCP server shuts down, a final consolidation runs automatically
+
+**For SDK users** — adapters support context managers that auto-wrap:
+
+```python
+from flowscript_agents.adapters.langgraph import FlowScriptStore
+
+with FlowScriptStore("agent-memory.json") as store:
+    # work happens — all mutations auto-save
+    store.put(("agents",), "key", {"value": "data"})
+# close() fires automatically → session_wrap() + save
+```
+
+After 20 sessions, your memory is a curated knowledge base, not a pile of notes. [Full lifecycle details →](docs/lifecycle.md)
+
+---
+
+## Description Integrity
+
+MCP tool descriptions are the prompts your LLM reads. If they're mutated in-process, the LLM silently follows poisoned instructions. The FlowScript MCP server includes three-layer integrity verification — a reference implementation of [deterministic description integrity for MCP](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2402):
+
+1. **`verify_integrity` tool** — LLM-callable. SHA-256 hashes of all tool definitions, deep-frozen at startup (`MappingProxyType`). Detects in-process mutation by malicious dependencies, monkey-patching, or middleware.
+2. **`flowscript://integrity/manifest` resource** — Host-verifiable. Claude Code / Cursor can verify descriptions without LLM involvement.
+3. **`tool-integrity.json`** — Build-time root of trust. Generated via `flowscript-mcp --generate-manifest`, ships in the package.
+
+Both the Python and [TypeScript](https://www.npmjs.com/package/flowscript-core) MCP servers implement this architecture. Honest threat model: detects in-process mutation, not supply chain or transport-layer attacks. [Full discussion →](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/2402)
 
 ---
 
@@ -311,7 +351,7 @@ Under the hood: a local semantic graph with typed nodes, typed relationships, an
 | [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 |
 
-**1,312 tests** across Python (581) and TypeScript (731). Same audit trail format and canonical JSON serialization across both languages.
+**1,315 tests** across Python (584) and TypeScript (731). Same audit trail format and canonical JSON serialization across both languages.
 
 ### Docs
 

{flowscript_agents-0.2.4 → flowscript_agents-0.2.6}/docs/lifecycle.md

@@ -20,7 +20,19 @@ print(report.growing)  # list of node IDs in growing tier
 print(report.dormant)  # candidates for pruning
 ```
 
-Dormant nodes are pruned to the audit trail during `close()` or `sessionWrap()` — archived with full hash-chain provenance, never destroyed.
+Dormant nodes are pruned to the audit trail during `close()` or `session_wrap()` — archived with full hash-chain provenance, never destroyed.
+
+## Why Session Wraps Matter
+
+Just like a mind needs sleep to consolidate memories, the reasoning graph needs regular session wraps to develop intelligence over time. A session wrap is the consolidation cycle — without it, knowledge accumulates as noise instead of maturing through the temporal tiers above.
+
+**Three mechanisms ensure consolidation happens:**
+
+1. **Explicit wrap** — the LLM calls `session_wrap` when the user signals session end (best results)
+2. **Auto-wrap** — the MCP server auto-consolidates after 5 minutes of inactivity (configurable via `FLOWSCRIPT_AUTO_WRAP_MINUTES` env var, `0` to disable)
+3. **Process exit** — a final consolidation runs automatically when the MCP server shuts down
+
+For SDK users, all adapters call `session_wrap()` via their `close()` method or context manager exit.
 
 ## The `with` Pattern (Recommended)
 
@@ -99,3 +111,44 @@ mem = Memory.load_or_create("file.json",
 ## Session Start Deduplication
 
 `sessionStart()` calls both `blocked()` and `tensions()` internally (for the orientation summary). Touches from these calls are deduplicated — nodes aren't double-touched just because they appeared in both query results.
+
+## Writing Your Own Adapter
+
+If you're building an adapter for a framework not yet supported, wire session wraps using this pattern:
+
+```python
+class MyFrameworkAdapter:
+    def __init__(self, file_path, embedder=None, llm=None, consolidation_provider=None):
+        self._memory = Memory.load_or_create(file_path)
+        self._unified = UnifiedMemory(
+            file_path=file_path, embedder=embedder,
+            llm=llm, consolidation_provider=consolidation_provider,
+        )
+        self._memory.set_adapter_context("my_framework", "MyFrameworkAdapter", "init")
+        self._memory.session_start()
+
+    def close(self):
+        """End the session: prune dormant nodes, save. Returns SessionWrapResult."""
+        try:
+            if self._unified:
+                return self._unified.close()
+            return self._memory.session_wrap()
+        finally:
+            self._memory.clear_adapter_context()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            self.close()
+        except Exception:
+            if exc_type is None:
+                raise  # close() failure IS the error when no prior exception
+```
+
+**Key points:**
+- `close()` should call `session_wrap()` (via `UnifiedMemory.close()` or directly)
+- `clear_adapter_context()` goes in the `finally` block AFTER `session_wrap()` — session lifecycle events need adapter attribution
+- Context managers (`__enter__`/`__exit__`) make the `with` pattern work
+- `set_adapter_context()` should be called on construction, then `set_adapter_operation()` per-operation for granular audit attribution

{flowscript_agents-0.2.4 → flowscript_agents-0.2.6}/examples/CLAUDE.md.example

@@ -27,13 +27,19 @@ just report what you found or stored. Treat memory like your own notes.
   consequences before committing.
 - **To correct mistakes:** Call `remove_memory` with a node_id (use
   `search_memory` first to find it) to remove incorrect or outdated entries.
-- **End of session:** When the user says "wrap up", "save what we learned",
-  or similar end-of-session phrases: review the conversation for any
-  decisions, tradeoffs, blockers, or reasoning that wasn't already stored
-  via `add_memory`. Save anything important you find. Then call
-  `session_wrap` to run lifecycle maintenance (graduation, pruning,
-  persist to disk). This is how memory gets smarter — each wrap
-  captures what matters and lets stale reasoning fade naturally.
+- **End of session:** When the user says "wrap up", "let's wrap",
+  "save what we learned", or signals the conversation is ending:
+  review for any decisions/tradeoffs/reasoning not yet stored via
+  `add_memory`, save what's important, then call `session_wrap`.
+  This is the reasoning graph's consolidation cycle — like sleep for
+  memory. Dormant nodes get pruned to the audit trail, frequently-used
+  knowledge graduates through temporal tiers (current → developing →
+  proven → foundation), and the graph gets smarter over time. Without
+  regular wraps, knowledge accumulates as noise instead of maturing.
+  NOTE: An auto-wrap safety net runs after 5 minutes of inactivity
+  and on process exit, but explicit wraps at session boundaries
+  produce the best results because you can review and store final
+  reasoning before consolidation happens.
 
 **What to remember (call `add_memory`):**
 - Decisions and their rationale ("We chose PostgreSQL because...")

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

@@ -43,7 +43,7 @@ from .memory import (
 )
 from .unified import UnifiedMemory
 
-__version__ = "0.2.0"
+__version__ = "0.2.5"
 __all__ = [
     "AuditConfig",
     "AuditQueryResult",