Ship agent memory without the plumbing.

What MemQL actually is.

Agent and voice deployments are integration-heavy. The engineering is mostly plumbing — vector store, orchestrator, tool registry, model provider, kept consistent by hand. MemQL collapses that plumbing into one declarative substrate on top of PostgreSQL and TimescaleDB.

A network of nodes built for three properties at once — the same three a crystal lattice gets for free. Watch.

// mcp· Author tools in MemQL once. They speak MCP — every tool is reachable by any MCP client.

Where agents plan, remember, and are held to account.

Storing data and reacting to events is table stakes. MemQL is where agents run whole tasks against a memory that behaves like memory — and where you can watch exactly what they did.

A plan fans into steps, each step leaves an observation, recall pulls the relevant ones back, and the whole run replays. Watch.

1@enabled
2@sdk
3@executor("integration.harnessRecall.recall")
4@args(profile="object", additionalProperties="true")
5@description("Recall top-k memories of a concept (default v1:harness:observation) by a SINGLE hybrid recency x relevance score: pgvector cosine similarity + exponential time-decay over createdAt, scored and ordered server-side in one SQL statement against the MemoryNodes hypertable (no app-side merge). Owner-scoped; window prunes hypertable chunks; halfLife + wSem/wRec are tunable.")
6builtin recall {
7  text      string  @required
8  concept   string
9  k         int
10  provider  string
11}

1// The whole agent working-state model — no external task
2// table, no audit log, no state store. (trimmed: real
3// concepts carry @description / @displayCard / @relationship.)
4
5concept plan {
6  ownerUserId  string  @required
7  goal         string  @required
8  status       enum("open", "running", "done", "failed", "cancelled")  @required @default("open")
9  rootStepId   string
10  input        object
11  result       object
12  provenanceMutation  string
13}
14
15concept step {
16  ownerUserId    string  @required
17  planId         string  @required
18  title          string  @required
19  status         enum("pending", "ready", "running", "blocked", "done", "failed")  @required @default("pending")
20  dependsOn      []string
21  idempotencyKey string  @required
22  attempt        int     @required @default("0")
23  result         object
24}
25
26concept observation {
27  ownerUserId  string  @required
28  stepId       string  @required
29  kind         enum("tool_result", "error", "note", "decision")  @required
30  content      string  @required
31  embedding    []float
32}

1@enabled
2@trigger(schedule="0 45 2 * * *")
3@description("Daily 02:45 UTC memory consolidation. Per owner: reads episodic nodes (plans / steps / observations) since that owner's watermark, groups them by similarity, LLM-distills stable facts, dedups against existing semantic memories, decays + prunes stale beliefs, then advances the watermark so the next run is incremental.")
4automation consolidateMemory {
5  step run {
6    logic consolidateMemory { event: event }
7  }
8}

// tools· calendar · notes · tasks · responsibilities — each a concept, a tool, and a skill. The Library subsystem stores and faceted-queries everything they produce.

// new here? · What is an AI harness? — the model-plus-harness primer, and where memory fits.

Three layers. One source tree.

Plain-text DSL on top, a single Go source tree in the middle, partition-isolated time-series storage underneath. Build tags decide which binary each node becomes.

  .memql files                authored as plain text
        ↓
  MemQL engine + SI router    one Go source tree,
        ↓                  build tags per node type
  PostgreSQL + TimescaleDB    partition-isolated
                              time-series storage

From a duct-taped stack to nine lines of MemQL.

A Postgres. A vector DB. An event bus. An OpenAI wrapper. A retry-logic file. Five systems, kept in sync by hand. You’ve built it. Drag the divider.

1# on_space_created.py — today
2from postgres import db
3from pinecone import vec
4from kafka import bus
5from openai import OpenAI
6
7oai = OpenAI()
8
9def on_space_created(payload):
10    if not payload["active"]:
11        return
12    space_id = payload["id"]
13    user_id  = payload["created_by"]
14    # join the user's default assistant
15    si = db.assistants.default_for(user_id)
16    db.memberships.insert(
17        space_id=space_id,
18        member_id=si.id,
19        role="assistant",
20    )
21    # ...specialist joins, audit emit, retries, idempotency,
22    # partition isolation, provider fallback — still TODO

1@enabled
2@trigger(event="node.created", concept="v1:cognition:space", partition="*")
3@filter(payload.active==true)
4@description("On space creation, joins the creator's assistant plus any specialist agents picked at creation time. Joiners' GAs are never auto-joined.")
5automation autoJoinSI {
6  step run {
7    logic autoJoinSI { event: event }
8  }
9}

One event. Five constructs. Zero glue.

The fragmented Python above is the stack you assemble by hand. Here is the same outcome, declared — one write ripples through five real constructs, and the engine handles the rest.

1@enabled
2@trigger(event="node.created", concept="v1:cognition:space", partition="*")
3@filter(payload.active==true)
4@description("On space creation, joins the creator's assistant plus any specialist agents picked at creation time. Joiners' GAs are never auto-joined.")
5automation autoJoinSI {
6  step run {
7    logic autoJoinSI { event: event }
8  }
9}

1@description("Triggered when a v1:cognition:space is created with status='active'. Auto-joins the creator's currently-active assistant as a v1:cognition:participant. The ONLY AI participant a space carries (maxAgents=1). Idempotent. Emits 'si.auto-joined'.")
2logic logicAutoJoinSI {
3  args {
4    event object @required
5  }
6  body {
7    getUser := queryUserById({ userId: args.event.payload.ownerUserId })
8    activeAssistantId := coalesce(getUser.First().payload.preferences.activeAssistantId, "")
9
10    // Exactly one of these fires, decided by activeAssistantId emptiness:
11    getActiveGA := if activeAssistantId != "" {
12      queryAgentById({ agentId: activeAssistantId })
13    }
14    getFallbackGA := if activeAssistantId == "" {
15      queryAssistantAgentForUser({ ownerUserId: args.event.payload.ownerUserId })
16    }
17    getGA := coalesce(getActiveGA, getFallbackGA)
18
19    // ...resolve the canonical agent id, then dispatch:
20    //   mutationJoinSpaceAsSI                (insert the SI participant)
21    //   mutationCreateSessionForParticipant  (bootstrap its session)
22  }
23}

A user creates a space. That insert emits a typed node.createdevent. An automation is already subscribed to it. It dispatches a piece of logic that resolves the user’s assistant and writes two rows — a participant and its session. Idempotency, partition isolation, audit provenance, and retries aren’t code you wrote. They’re the substrate.

Twelve constructs. One file format.

Every behavior in the system is described as a typed construct in a .memql file. The vocabulary is small. The system is what those twelve nouns compose into.

1@description("A streaming text chunk emitted incrementally during AI response generation.")
2concept chunk {
3  done           bool    @required
4  index          int     @required
5  participantId  string  @required
6  replyId        string  @required
7  spaceId        string  @required
8  text           string  @required
9
10  @relationship(type="parent",    field="spaceId",       target="v1:cognition:space")
11  @relationship(type="createdBy", field="participantId", target="v1:cognition:participant")
12}

Three readers.