AI Agents

Use Meridian CRDTs as shared state for AI agents — Anthropic, OpenAI, and Gemini.

Meridian ships built-in tool use helpers for AI agents. Stateless agents (serverless functions, Lambda, Cloudflare Workers) can read and write CRDTs via pure HTTP — no persistent WebSocket required.

getMeridianTools() returns Anthropic-compatible tool definitions by default. Use toOpenAITools() or toGeminiTools() to convert to the format expected by OpenAI or Gemini.

​

Install

# Anthropic
npm install meridian-sdk @anthropic-ai/sdk

# OpenAI
npm install meridian-sdk openai

# Gemini
npm install meridian-sdk @google/generative-ai

​

Quick start

import Anthropic from "@anthropic-ai/sdk";
import { getMeridianTools, executeMeridianTool } from "meridian-sdk";
import type { ToolUseBlock } from "meridian-sdk";

const config = {
  baseUrl: "https://your-meridian-server.com",
  token: process.env.MERIDIAN_TOKEN!,
  namespace: "my-app",
};

const anthropic = new Anthropic();

// 1. Generate Anthropic-compatible tool definitions from your CRDT IDs
const tools = getMeridianTools(config, ["views", "notes", "tags"]);

// 2. Run the agentic loop
const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "Increment the views counter and update the notes." },
];

while (true) {
  const response = await anthropic.messages.create({
    model: "claude-opus-4-6",
    max_tokens: 1024,
    tools,
    messages,
  });

  const toolResults: Anthropic.ToolResultBlockParam[] = [];

  for (const block of response.content) {
    if (block.type === "tool_use") {
      // 3. Execute each tool call against Meridian via HTTP
      const result = await executeMeridianTool(config, block as ToolUseBlock);
      toolResults.push({ type: "tool_result", tool_use_id: block.id, content: result });
    }
  }

  messages.push({ role: "assistant", content: response.content });

  if (toolResults.length === 0) break; // Claude is done

  messages.push({ role: "user", content: toolResults });
}

​

OpenAI

import OpenAI from "openai";
import { getMeridianTools, toOpenAITools, executeOpenAITool } from "meridian-sdk";

const openai = new OpenAI();
const tools = toOpenAITools(getMeridianTools(config, ["views", "notes", "tags"]));

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  tools,
  messages: [{ role: "user", content: "Increment views and update notes." }],
});

const msg = response.choices[0].message;
const toolResults = [];

for (const call of msg.tool_calls ?? []) {
  // Pass call directly — no wrapping needed
  const result = await executeOpenAITool(config, call);
  toolResults.push({ role: "tool", tool_call_id: call.id, content: result });
}

​

Gemini

import { GoogleGenerativeAI } from "@google/generative-ai";
import { getMeridianTools, toGeminiTools, executeGeminiTool } from "meridian-sdk";

const genai = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const model = genai.getGenerativeModel({
  model: "gemini-1.5-pro",
  tools: [toGeminiTools(getMeridianTools(config, ["views", "notes", "tags"]))],
});

const result = await model.generateContent("Increment views and update notes.");
const parts = result.response.candidates?.[0].content.parts ?? [];

for (const part of parts) {
  if (part.functionCall) {
    // Pass part.functionCall directly — no id hack, no wrapping
    const toolResult = await executeGeminiTool(config, part.functionCall);
    // pass toolResult back as functionResponse part
  }
}

​

getMeridianTools

function getMeridianTools(
  config: MeridianAgentConfig,
  crdtIds: string[],
): Tool[]

Returns an Anthropic Tool[] array. Each CRDT ID exposes four tools:

Tool	CRDT type	Description
meridian_read_{id}	any	Read current JSON state
meridian_increment_{id}	GCounter / PNCounter	Increment by amount
meridian_set_{id}	LWW Register	Set value (string, number, object)
meridian_add_{id}	ORSet	Add an element

Special characters in CRDT IDs (:, /, -) are replaced with _ in tool names.

​

executeMeridianTool

function executeMeridianTool(
  config: MeridianAgentConfig,
  toolUse: ToolUseBlock,
): Promise<string>

Executes a tool call returned by Claude and returns a JSON string suitable for the content field of a tool_result block.

Dispatches to the correct HTTP endpoint based on the tool name:

• read → GET /v1/namespaces/:ns/crdts/:id
• increment → POST /v1/namespaces/:ns/crdts/:id/ops (GCounter or PNCounter op)
• set → POST /v1/namespaces/:ns/crdts/:id/ops (LwwRegister op)
• add → POST /v1/namespaces/:ns/crdts/:id/ops (ORSet Add op)

​

toOpenAITools

function toOpenAITools(tools: Tool[]): OpenAITool[]

Converts Meridian tools to OpenAI Chat Completions format ({ type: "function", function: { name, description, parameters } }).

​

toGeminiTools

function toGeminiTools(tools: Tool[]): GeminiTool

Converts Meridian tools to Google Gemini format ({ functionDeclarations: [...] }). Returns a single GeminiTool object to pass directly in the tools array of model.generateContent().

​

executeOpenAITool

function executeOpenAITool(
  config: MeridianAgentConfig,
  toolCall: OpenAIToolCall,
): Promise<string>

Executes a tool call from OpenAI. OpenAIToolCall structurally matches ChatCompletionMessageToolCall from the openai package — pass tool_calls[n] directly. Parses function.arguments (JSON string) internally.

​

executeGeminiTool

function executeGeminiTool(
  config: MeridianAgentConfig,
  functionCall: GeminiFunctionCall,
): Promise<string>

Executes a tool call from Gemini. GeminiFunctionCall structurally matches FunctionCall from @google/generative-ai — pass part.functionCall directly.

​

MeridianAgentConfig

interface MeridianAgentConfig {
  /** HTTP base URL of the Meridian server */
  baseUrl: string;
  /** Bearer token with read+write permissions for the namespace */
  token: string;
  /** Namespace scoping all CRDT operations */
  namespace: string;
}

​

Persistent agent memory

Because Meridian CRDTs are durable, an agent can use them as long-term memory across runs — reading its previous state at startup and writing an updated summary before exiting.

// On startup — read previous memory
const lastRun = await fetch(`${baseUrl}/v1/namespaces/${ns}/crdts/memory-last-run`, {
  headers: { Authorization: `Bearer ${token}` },
}).then(r => r.ok ? r.json() : null);

// Pass previous memory as context to Claude
const prompt = lastRun
  ? `Your last run summary: ${JSON.stringify(lastRun.value)}\n\nContinue from where you left off.`
  : `This is your first run.`;

// ... agentic loop ...

// On exit — write updated memory
await executeMeridianTool(config, {
  type: "tool_use", id: "1", name: "meridian_set_memory_last_run",
  input: { value: JSON.stringify({ timestamp: new Date(), summary: "..." }), client_id: 1 },
});

A full working example is in examples/ai-agents/agents/memory.ts. It uses three CRDTs (namespace: ai-agents):

CRDT	Type	Purpose
memory-run-count	GCounter	Total runs ever
memory-last-run	LWW Register	Summary of the last run
memory-insights	ORSet	Observations accumulated across all runs

CRDT IDs must use hyphens only — colons are not supported. getMeridianTools converts special characters to _ in tool names and executeMeridianTool converts them back to - when calling the API.

​

Multi-agent debate

Two agents can use CRDTs as a shared communication channel — each writing its argument to an LWW-Register and reading the opponent’s latest argument before composing a rebuttal.

A full working example is in examples/ai-agents/agents/debate.ts. It runs two Claude agents (FOR / AGAINST) in interleaved rounds, with each agent’s argument history accumulated in an ORSet. A React UI displays both sides live.

​

Live UI

The AI agents example ships a React dashboard with four tabs — Agents (multi-worker coordinator), Tool Use (single Claude agent), Memory (persistent memory across runs), and Debate (two-agent debate) — all subscribing to the same CRDTs via WebSocket and displaying live state as agents write.

​

SSE streaming

For agents that need to react to changes without polling, use the SSE endpoint:

GET /v1/namespaces/:ns/crdts/:id/events
Authorization: Bearer <token>
Accept: text/event-stream

Each event is a base64-encoded msgpack delta. The SDK HttpClient.syncCrdt() handles decoding automatically. Keep-alive pings are sent every 15 seconds to prevent proxy timeouts.

const es = new EventSource(
  `${baseUrl}/v1/namespaces/${ns}/crdts/${id}/events`,
  { headers: { Authorization: `Bearer ${token}` } }
);

es.onmessage = (e) => {
  const delta = decode(base64ToBytes(e.data)); // msgpack delta
  // apply delta to local CRDT state
};

​

Token requirements

The token must have read and write permissions for all CRDT IDs the agent will access. Issue one via the admin API:

curl -X POST https://your-server.com/v1/tokens \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "my-app",
    "client_id": 42,
    "permissions": { "read": ["*"], "write": ["*"], "admin": false }
  }'

See Tokens for details.