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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowscript-agents
-Version: 0.2.1
+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
@@ -111,10 +111,37 @@ 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": {
+    "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 +152,44 @@ 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
+```
+
+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"]
 ```
 
-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.
+| 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.
 
@@ -289,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.1 → flowscript_agents-0.2.2}/README.md

@@ -47,10 +47,37 @@ 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": {
+    "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 +88,44 @@ 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
+```
+
+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"]
 ```
 
-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.
+| 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.
 
@@ -225,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.1 → 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.1 → flowscript_agents-0.2.2}/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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flowscript-agents"
-version = "0.2.1"
+version = "0.2.2"
 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"