# Flowscript

> Queryable reasoning memory for AI agents. Six typed queries (why, tensions, blocked, whatIf, alternatives, counterfactual) over reasoning graphs. Vector stores remember what. FlowScript remembers why. TypeScript SDK + MCP server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-phillipclapham-flowscript`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [phillipclapham](https://agentstack.voostack.com/s/phillipclapham)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [phillipclapham](https://github.com/phillipclapham)
- **Source:** https://github.com/phillipclapham/flowscript
- **Website:** https://flowscript.org

## Install

```sh
agentstack add mcp-phillipclapham-flowscript
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

FlowScript

Semantic notation for structured reasoning

21 typed markers for encoding decisions, tensions, blockers, causal chains, and temporal knowledge.

  
  
  
  

---

> **Evolution note:** FlowScript explored typed reasoning representation for AI agents — compression-as-cognition, temporal graduation, citation-validated patterns, immune system. These core concepts evolved into [**anneal-memory**](https://github.com/phillipclapham/anneal-memory), a two-layer memory system for AI agents. The notation remains in active daily use for reasoning compression and knowledge encoding. This repo is maintained as a reference implementation and notation playground.

---

## The Notation

FlowScript is a 21-marker semantic notation that both humans and AI parse natively. It sits between natural language (ambiguous, verbose) and formal logic (precise, unreadable). Start with three markers — `->`, `> sub-ms reads, proven at scale
  || PostgreSQL -> rich queries, $15/month, ACID

  speed >
  

- CodeMirror 6 with custom FlowScript language mode and syntax highlighting
- D3 force-directed graph visualization of reasoning nodes and relationships
- Live query panel — run `tensions()`, `blocked()`, `why()` against your graph in the browser
- WCAG AA accessible, responsive design

Source code in [`web/`](web/).

### Notation Spec

The full FlowScript v2.1 specification in [`spec/`](spec/):
- `semantics.md` — all 21 markers formally defined
- `grammar.md` — EBNF formal grammar
- `ir.schema.json` — JSON schema for the intermediate representation
- `linter-rules.md` — semantic validation rules (6 errors, 3 warnings)

### Teaching Materials

- [`FLOWSCRIPT_SYNTAX.md`](FLOWSCRIPT_SYNTAX.md) — comprehensive syntax reference with examples
- [`FLOWSCRIPT_LEARNING.md`](FLOWSCRIPT_LEARNING.md) — conceptual introduction
- [`FLOWSCRIPT_EXAMPLES.md`](FLOWSCRIPT_EXAMPLES.md) — real-world patterns (before/after)
- [`ADVANCED_PATTERNS.md`](ADVANCED_PATTERNS.md) — recursive nesting, meta-thoughts, metaprogramming
- [`examples/`](examples/) — four golden examples (Decision, Debug, Research, Design) with teaching guides

---

## What Evolved into anneal-memory

Through building FlowScript, we discovered that the core insights were more powerful than the syntax:

| FlowScript explored | anneal-memory delivers |
|:---------------------|:----------------------|
| Temporal graduation (1x → 2x → 3x → proven) | Citation-validated graduation with immune system |
| Compression-as-cognition | Episodes compress into identity through consolidation |
| Hash-chained audit trail | Tamper-evident compliance layer (EU AI Act) |
| Anti-inbreeding defense | Graduation gate + principle demotion through citation decay |
| Transport-layer wrapper | Compliance proxy vision (MCP transport interception) |
| Six typed reasoning queries | Planned for anneal-memory CLI |

The notation barrier was real — developers won't learn a new syntax for memory. anneal-memory delivers the same cognitive architecture as a zero-dependency MCP server where agents use natural language.

**[anneal-memory on GitHub](https://github.com/phillipclapham/anneal-memory)** | **[anneal-memory on PyPI](https://pypi.org/project/anneal-memory/)**

---

## Related

- **[flowscript-agents](https://github.com/phillipclapham/flowscript-agents)** — Python SDK with MCP server, nine framework adapters, 717 tests
- **[anneal-memory](https://github.com/phillipclapham/anneal-memory)** — Where the core concepts live now
- **[flowscript.org](https://flowscript.org)** — Notation reference, Learn page, and interactive playground

---

  Built by Phill Clapham · Clapham Digital LLC

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [phillipclapham](https://github.com/phillipclapham)
- **Source:** [phillipclapham/flowscript](https://github.com/phillipclapham/flowscript)
- **License:** MIT
- **Homepage:** https://flowscript.org

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-phillipclapham-flowscript
- Seller: https://agentstack.voostack.com/s/phillipclapham
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.