Skip to content
Embabel Worlds

CypherScript — Cypher woven into TypeScript/JavaScript

Anywhere a realm ships code that runs in the host’s code_mode sandbox — a routine (agents/), a decoration action, a skill recipe — it writes CypherScript: an ordinary TypeScript/JavaScript program that interleaves graph queries with procedural logic, integration calls, and inline LLM, all over the one typed gateway.* surface. It is not a separate language — it’s TS/JS with first-class graph access:

  • Cypher for the graph — await gateway.kg.query({ cypher, params }). The query runs through Virtual Cypher (above): rewritten to the host-bound world, context, and access policy, read-only, and materializing on-demand virtual joins exactly as a chat query would — so one MATCH spans persisted and virtual (integration) data.
  • TypeScript/JavaScript for what Cypher can’t express — branching, aggregation, reshaping, loops.
  • Integrations — gateway.<ns>.* (the Realm’s own Functions + connected APIs), e.g. fetch the actual email body the graph only holds an edge for.
  • Inline LLM — gateway.ai.classify / gateway.ai.* for fuzzy predicates Cypher can’t state.
// CypherScript: a graph query (through Virtual Cypher) + JS + integration + LLM in ONE program.
const people = await gateway.kg.query({
  cypher: `MATCH (me:AssistantUser)-[:EMAILED]->(p:Person)-[:HAS_GITHUB]->(g:GitHubIdentity)-[:RAISED]->(i:GitHubIssue)
           WHERE toLower(p.name) CONTAINS $who
           RETURN p.name AS name, collect(i.title) AS issues`,
  params: JSON.stringify({ who: "governor" }),
});
const busy = people.filter(p => p.issues.length > 5);              // plain JS
for (const p of busy) {
  const verdict = await gateway.ai.classify({ text: p.issues.join("\n"), labels: ["bug", "feature"] }); // inline LLM
  if (!dryRun) await gateway.notifications.createNotification({ event: "BusyContributor", source: "demo", url: "" });
}

params supplies bound query values as a JSON object; a JSON-encoded object is also supported. Bind values with $name parameters. Reads and model calls can expose private data and require the applicable host approvals. A handler’s dryRun flag controls its proposed effects; it does not provide authorization. Compatibility lenses can use the host code-mode gateway. Captured installations use the handler-binding profile below. Virtual Cypher calls are available to a captured handler once the owner separately approves cypher_query, following the captured graph-query profile.