flowscript

---

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, 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 — ->, ><, { } — and add more as you need them.

{database_decision:
  ? which_database_for_sessions
  || Redis -> sub-ms reads, proven at scale
  || PostgreSQL -> rich queries, $15/month, ACID

  speed ><[performance vs cost] infrastructure budget

  [decided(rationale: "budget constraint eliminated Redis", on: "2026-03-30")]
  ! [blocked(reason: "data export tool needed", since: "2026-03-28")]
}

Every marker has computational semantics. ? creates a question node. || creates alternatives. >< creates a tension with a named axis. [decided] records a commitment with rationale and date. The parser turns this into the same IR that the query engine traverses.

Learn the full notation: flowscript.org/learn | Formal spec: spec/ directory (757 lines, v2.1)

---

What This Repo Contains

TypeScript SDK (flowscript-core on npm)

779 tests. Memory class with typed node construction, six graph traversal queries, 15 agent tools in OpenAI function calling format, hash-chained audit trail, and four token budgeting strategies.

import { Memory } from 'flowscript-core';

const mem = Memory.loadOrCreate('./agent-memory.json');

// Build reasoning — typed nodes with explicit relationships
const q = mem.question("Which database for agent memory?");
mem.alternative(q, "Redis").decide({ rationale: "speed critical" });
mem.alternative(q, "SQLite").block({ reason: "no concurrent writes" });
mem.tension(mem.thought("sub-ms reads"), mem.thought("$200/mo cluster"), "performance vs cost");

// Six typed queries over the reasoning graph
mem.query.tensions();             // tradeoffs with named axes
mem.query.blocked();              // what's stuck + downstream impact
mem.query.why(nodeId);            // causal chain backward
mem.query.whatIf(nodeId);         // what breaks if this changes
mem.query.alternatives(nodeId);   // what was considered + decided
mem.query.counterfactual(nodeId); // what would need to change

// Human-readable serialization
console.log(mem.toFlowScript());