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

flowscript_agents-0.2.3/.github/workflows/test.yml

@@ -0,0 +1,86 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test-core:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ['3.11', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run core tests
+        run: |
+          pytest tests/test_memory.py tests/test_audit.py tests/test_consolidation.py tests/test_embeddings.py tests/test_mcp.py -v --tb=short
+
+  test-mcp-smoke:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install from PyPI (simulates real user)
+        run: pip install flowscript-agents
+
+      - name: Verify import
+        run: python -c "from flowscript_agents import Memory, UnifiedMemory; print('Import OK')"
+
+      - name: MCP server stdio handshake
+        shell: python
+        run: |
+          import subprocess, json, sys, time
+
+          proc = subprocess.Popen(
+              [sys.executable, '-m', 'flowscript_agents.mcp', '--memory', './test-memory.json'],
+              stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+              text=True
+          )
+          time.sleep(2)
+
+          # Send initialize
+          msg = json.dumps({
+              'jsonrpc': '2.0', 'id': 1, 'method': 'initialize',
+              'params': {
+                  'protocolVersion': '2025-03-26',
+                  'capabilities': {},
+                  'clientInfo': {'name': 'ci-test', 'version': '1.0'}
+              }
+          })
+          proc.stdin.write(msg + '\n')
+          proc.stdin.flush()
+          time.sleep(1)
+
+          response = proc.stdout.readline()
+          assert response, 'No response from MCP server'
+          data = json.loads(response)
+          assert 'result' in data, f'Bad response: {data}'
+
+          info = data['result'].get('serverInfo', {})
+          print(f"MCP server OK: {info.get('name')} v{info.get('version')}")
+
+          tools_count = len(data['result'].get('capabilities', {}).get('tools', {}))
+          print(f"Platform: {sys.platform}")
+          print(f"Python: {sys.version}")
+
+          proc.terminate()
+          print('PASS: MCP stdio handshake works')

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: flowscript-agents
-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.
+Version: 0.2.3
+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
 Project-URL: Issues, https://github.com/phillipclapham/flowscript-agents/issues
@@ -62,9 +62,13 @@ Provides-Extra: smolagents
 Requires-Dist: smolagents>=1.0.0; extra == 'smolagents'
 Description-Content-Type: text/markdown
 
-# flowscript-agents
+<p align="center">
+  <img src="docs/brand/logo-512.png" alt="FlowScript" width="120" />
+</p>
+
+<h1 align="center">flowscript-agents</h1>
 
-**Agent memory that tracks why you decided, what conflicts, and what's blocked. Not just what was said.**
+<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/)
 
@@ -107,14 +111,51 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 
 ---
 
+## Why FlowScript
+
+Agent memory stores what happened. FlowScript stores why.
+
+Most agent infrastructure is converging on authorization — identity, access control, audit trails for *who did what*. That's necessary. But it leaves a gap: your agent can prove it was *allowed* to make a decision, but not *why* it made it. Researchers call this "[strategic blindness](https://arxiv.org/abs/2603.18718)" — memory that tracks content without tracking reasoning.
+
+FlowScript sits above your memory store, not instead of it. Google Memory Bank, LangGraph checkpointers, Mem0 — they remember what your agent stored. FlowScript remembers why it decided, what it traded off, and what breaks if you change your mind.
+
+---
+
 ## Get Started
 
 ### 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": {
+    "flowscript": {
+      "command": "flowscript-mcp",
+      "args": ["--memory", "./project-memory.json"],
+      "env": {
+        "OPENAI_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+**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": {
@@ -125,11 +166,52 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 }
 ```
 
+**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`. 13 reasoning tools.
+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.
+
+**Using Anthropic instead of OpenAI:**
+
+With `ANTHROPIC_API_KEY` set, the server auto-configures extraction and consolidation using Claude Haiku. No vector search (Anthropic has no embedding API), but keyword + temporal search works well. To use a different Anthropic model:
+
+```json
+"args": ["--memory", "./project-memory.json", "--llm-model", "claude-sonnet-4-6"]
+```
 
 **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.
 
@@ -289,7 +371,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.1 → flowscript_agents-0.2.3}/README.md

@@ -1,6 +1,10 @@
-# flowscript-agents
+<p align="center">
+  <img src="docs/brand/logo-512.png" alt="FlowScript" width="120" />
+</p>
+
+<h1 align="center">flowscript-agents</h1>
 
-**Agent memory that tracks why you decided, what conflicts, and what's blocked. Not just what was said.**
+<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/)
 
@@ -43,14 +47,51 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 
 ---
 
+## Why FlowScript
+
+Agent memory stores what happened. FlowScript stores why.
+
+Most agent infrastructure is converging on authorization — identity, access control, audit trails for *who did what*. That's necessary. But it leaves a gap: your agent can prove it was *allowed* to make a decision, but not *why* it made it. Researchers call this "[strategic blindness](https://arxiv.org/abs/2603.18718)" — memory that tracks content without tracking reasoning.
+
+FlowScript sits above your memory store, not instead of it. Google Memory Bank, LangGraph checkpointers, Mem0 — they remember what your agent stored. FlowScript remembers why it decided, what it traded off, and what breaks if you change your mind.
+
+---
+
 ## Get Started
 
 ### 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": {
+    "flowscript": {
+      "command": "flowscript-mcp",
+      "args": ["--memory", "./project-memory.json"],
+      "env": {
+        "OPENAI_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+**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": {
@@ -61,11 +102,52 @@ Five queries that no vector store can answer — `why()`, `tensions()`, `blocked
 }
 ```
 
+**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`. 13 reasoning tools.
+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.
+
+**Using Anthropic instead of OpenAI:**
+
+With `ANTHROPIC_API_KEY` set, the server auto-configures extraction and consolidation using Claude Haiku. No vector search (Anthropic has no embedding API), but keyword + temporal search works well. To use a different Anthropic model:
+
+```json
+"args": ["--memory", "./project-memory.json", "--llm-model", "claude-sonnet-4-6"]
+```
 
 **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.
 
@@ -225,7 +307,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.1 → flowscript_agents-0.2.3}/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.1 → flowscript_agents-0.2.3}/flowscript_agents/__init__.py

@@ -3,7 +3,7 @@ FlowScript Agents — Complete agent memory: reasoning + vector + auto-extractio
 
 Decision intelligence memory for AI agent frameworks. Drop-in provider for
 LangGraph, CrewAI, Google ADK, OpenAI Agents SDK, Pydantic AI, smolagents,
-LlamaIndex, Haystack, CAMEL-AI, and Vercel AI SDK.
+LlamaIndex, Haystack, and CAMEL-AI.
 
 What Mem0 does, plus what Mem0 can't: typed semantic queries (why, tensions,
 blocked, alternatives, whatIf) over agent reasoning with temporal intelligence.

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

@@ -13,19 +13,30 @@ Full config:
     python -m flowscript_agents.mcp --memory ./agent.json \\
         --embedder openai --llm-model gpt-4o-mini
 
-Configure in your project's .mcp.json (project-level, shareable):
+Configure in your editor's MCP settings:
+
+Claude Code — .claude/settings.json (project or ~/.claude/settings.json global):
 {
   "mcpServers": {
     "flowscript": {
-      "type": "stdio",
-      "command": "python3",
-      "args": ["-m", "flowscript_agents.mcp", "--memory", "./agent-memory.json"],
+      "command": "flowscript-mcp",
+      "args": ["--memory", "./agent-memory.json"],
       "env": { "OPENAI_API_KEY": "sk-..." }
     }
   }
 }
 
-Or in ~/.claude.json for global (all projects) configuration.
+Cursor / Windsurf / VS Code — .mcp.json in project root:
+{
+  "mcpServers": {
+    "flowscript": {
+      "type": "stdio",
+      "command": "flowscript-mcp",
+      "args": ["--memory", "./agent-memory.json"],
+      "env": { "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
 
 When OPENAI_API_KEY is set, the server auto-configures:
 - OpenAI embeddings (text-embedding-3-small) for vector search

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

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowscript-agents"
-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."
+version = "0.2.3"
+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, and CAMEL-AI."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"