Python SDK for FlowScript reasoning memory
MCP server, nine framework adapters, typed reasoning queries, hash-chained audit trail.
Evolution note: The architecture explored here — transport-layer interception, consolidation engine, anti-inbreeding defense, hash-chained audit trail, temporal graduation — directly informed anneal-memory, a two-layer memory system for AI agents that delivers these concepts as a zero-dependency MCP server. This repo is maintained as a reference implementation.
flowscript-agents is the Python SDK for FlowScript reasoning memory. It provides:
- 20 MCP tools for reasoning memory in Claude Code, Cursor, and other MCP-compatible editors
- Nine framework adapters (LangGraph, CrewAI, Google ADK, OpenAI Agents, Pydantic AI, smolagents, LlamaIndex, Haystack, CAMEL-AI)
- Six typed reasoning queries —
why(),tensions(),blocked(),alternatives(),whatIf(),counterfactual()— graph traversals, not text search - Consolidation engine — typed operations (ADD/UPDATE/RELATE/RESOLVE/NONE) where contradictions become queryable tensions instead of silent deletions
- Hash-chained audit trail — SHA-256 linked, append-only, crash-safe, framework attribution, SIEM callbacks
- SDK wrapper — transport-layer interception for OpenAI/Anthropic clients (agent never knows)
717 tests. Published on PyPI. MIT licensed.
These are graph traversals — sub-millisecond, deterministic, no LLM calls.
| Query | Returns | Ask when |
|---|---|---|
query_why(node_id) |
Causal chain backward from any decision | "Why did we choose this?" |
query_tensions() |
Tradeoffs with named axes | "What tradeoffs are we navigating?" |
query_blocked() |
Blockers + downstream impact | "What's stuck and what does it affect?" |
query_alternatives(node_id) |
Options considered + outcome | "What else did we consider?" |
query_what_if(node_id) |
Forward impact analysis | "What breaks if we change this?" |
query_counterfactual(node_id) |
What would need to change | "What would it take to reverse this?" |
No vector store can answer these. Embedding similarity tells you what looks like your query. These queries tell you what caused, blocked, traded off against, and follows from your agent's decisions.
Most memory systems handle contradictions by deleting. Mem0's consolidation uses ADD/UPDATE/DELETE — when facts contradict, the old one is replaced.
FlowScript doesn't delete. It relates.
When consolidation detects a contradiction, it creates a tension with a named axis. Both perspectives survive. The disagreement itself becomes queryable knowledge. This approach satisfies AGM belief revision postulates — the formal framework proving deletion is mathematically irrational for a reasoning agent.
Each adapter implements your framework's native memory interface. You don't learn a new API — you get reasoning queries on top of the one you already use.
| Framework | Adapter | Install |
|---|---|---|
| LangGraph | FlowScriptStore → BaseStore |
pip install flowscript-agents[langgraph] |
| CrewAI | FlowScriptStorage → StorageBackend |
pip install flowscript-agents[crewai] |
| Google ADK | FlowScriptMemoryService → BaseMemoryService |
pip install flowscript-agents[google-adk] |
| OpenAI Agents | FlowScriptSession → Session |
pip install flowscript-agents[openai-agents] |
| Pydantic AI | FlowScriptDeps → Deps + tools |
pip install flowscript-agents[pydantic-ai] |
| smolagents | FlowScriptMemory → Tool protocol |
pip install flowscript-agents[smolagents] |
| LlamaIndex | FlowScriptMemoryBlock → BaseMemoryBlock |
pip install flowscript-agents[llamaindex] |
| Haystack | FlowScriptMemoryStore → MemoryStore |
pip install flowscript-agents[haystack] |
| CAMEL-AI | FlowScriptCamelMemory → AgentMemory |
pip install flowscript-agents[camel-ai] |
All adapters expose .memory for direct query access and support with blocks for automatic session lifecycle.
| flowscript-agents explored | anneal-memory delivers |
|---|---|
| Consolidation engine (ADD/UPDATE/RELATE/RESOLVE) | Compression-as-cognition through session wraps |
| Anti-inbreeding defense (citation validation) | Graduation gate + principle demotion |
| Hash-chained audit trail | Tamper-evident compliance layer |
| Transport-layer SDK wrapper | Compliance proxy vision (MCP interception) |
| 9-marker FlowScript subset for compression | Same subset, zero-dependency MCP |
| Temporal graduation (current → developing → proven → foundation) | Citation-validated graduation with immune system |
| Continuity file compression | Two-layer memory: episodes compress into identity |
anneal-memory delivers these concepts without requiring notation learning, API key configuration, or framework-specific adapters. Zero dependencies. Install and go.
anneal-memory on GitHub | anneal-memory on PyPI
- API Reference — Full Python SDK documentation
- Adapter Guide — Per-framework integration examples
- Session Lifecycle — Temporal tiers and session wraps
- Audit Trail — Hash-chain architecture and compliance
- CLAUDE.md snippet — Instructions for agents using FlowScript tools
- FlowScript (TypeScript) — TypeScript SDK, notation spec, web editor, 779 tests
- anneal-memory — Where the core concepts live now
- flowscript.org — Notation reference and interactive playground
Built by Phill Clapham · Clapham Digital LLC