Why ECHO?

ECHO is the data model that applications and agents share. Plugins code against its objects instead of keeping private stores. An agent keeps its memory in the same graph, and can inspect the schema of everything in it. Data from external systems lands there as linked objects, so one query can reach all of it.

Agents need memory they can query

A conversation ends and its context goes with it. An agent that works across sessions needs somewhere durable to put what it learned, and that memory is only useful if it connects to the work it is about.

In ECHO a memory is an ordinary object. It has a type, it can reference the issue it is about, and it comes back through the same query an application uses. The org.dxos.skill.memory skill stores an agent’s memories this way.

class Memory extends Type.makeObject<Memory>(DXN.make('com.example.type.memory', '0.1.0'))(
  Schema.Struct({
    title: Schema.String,
    content: Schema.String,
    about: Schema.optional(Ref.Ref(Issue)),
  }),
) {}

const issue = db.add(Obj.make(Issue, { title: 'Sync drops the last page' }));
db.add(Obj.make(Memory, { title: 'Root cause', content: 'The cursor skips short pages.', about: Ref.make(issue) }));

const recalled = await db.query(Query.select(Filter.type(Memory))).run();

Because memory is not a separate store, it replicates with the rest of the space, and any code that can query the space can read it.

An agent can only use what it can inspect

An agent has no compiled types. It works from what it can read at run time, so the schema has to be data, not only a TypeScript declaration.

Every ECHO type reports its name, version and metadata at run time, and converts to JSON Schema, the format tool parameters already use. org.dxos.echo#F-2.3 The schema goes the other way too: a type built from JSON Schema and added to a database replicates like any object, so an agent can define a new type while it runs.

const typename = Type.getTypename(Memory);
const version = Type.getVersion(Memory);
const parameters = JsonSchema.toJsonSchema(Memory);

const Contact = Type.makeObjectFromJsonSchema({
  typename: 'com.example.type.contact',
  version: '0.1.0',
  jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ name: Schema.String })),
});
await db.addType(Contact);

The database skill in plugin-space gives agents this through its QueryTypes and AddType operations. An agent can look up what a space holds before it writes, instead of guessing at field names.

External data needs somewhere to meet

Mail, issues and calendars live in systems that do not know about each other. Syncing them into ECHO makes each record an object, with a foreign key that records where it came from. A Ref can then link a GitHub issue to a Linear task, or to the note that discusses both.

The foreign key is what makes a repeat sync safe. Look the record up by its key, then update the object you found or add a new one, and the record does not end up in the graph twice.

const key = { source: 'github.com', id: '1234' };

const [existing] = await db.query(Query.select(Filter.foreignKeys(Issue, [key]))).run();
if (existing) {
  Obj.update(existing, (existing) => {
    existing.title = 'Sync drops the last page';
  });
} else {
  db.add(Obj.make(Issue, { [Obj.Meta]: { keys: [key] }, title: 'Sync drops the last page' }));
}

plugin-github and plugin-linear sync this way. Once the data is in the graph, the code that reads it does not need to know which system it came from.

Plugins code against the data model

A plugin declares its types with Type.makeObject and contributes them to the schema registry. Its UI, its operations and the agents that use it all read and write the same objects. There is no plugin-specific API in between, so a second plugin can select the first plugin’s objects by type.

The rest of this page is the argument for the model itself. Keeping state on a server means client code spends its time on copies: caches, optimistic updates, retry queues and conflict handling. ECHO moves the state onto the device. Objects are CRDT documents in a local database, so a write is finished when the call returns, and peers merge their changes when they connect.

The ECHO pattern

An ECHO type is a class that declares one schema. The class is the runtime schema and the TypeScript type of its instances.

class Person extends Type.makeObject<Person>(DXN.make('com.example.type.person', '0.1.0'))(
  Schema.Struct({ name: Schema.String }),
) {}

class Task extends Type.makeObject<Task>(DXN.make('com.example.type.task', '0.1.0'))(
  Schema.Struct({
    title: Schema.String,
    done: Schema.Boolean,
    assignee: Schema.optional(Ref.Ref(Person)),
  }),
) {}

Reading the signature left to right:

class Task extends

Type.makeObjectan object type

<Task>instance type

(dxn)global type name and version

(schema)Effect Schema of the fields

{}

Instances are live objects. You add them to a database, change them with Obj.update, and select them with a typed query.

const ada = db.add(Obj.make(Person, { name: 'Ada' }));
const task = db.add(Obj.make(Task, { title: 'Review', done: false, assignee: Ref.make(ada) }));

Obj.update(task, (task) => {
  task.done = true;
});

const finished = await db.query(Query.select(Filter.type(Task, { done: true }))).run();

Nothing here waits on a network. db.add and Obj.update apply locally and return, and finished already contains the task. org.dxos.echo.query#F-2

Don’t rebuild the data layer

Here is one task, marking an item as done, written against a REST API and against ECHO. The REST version is not careless. It is the minimum that handles a slow network, an offline user and a concurrent edit, and it still has two open questions in its comments.

REST, cache and queue

const finish = async (id: string) => {
  const previous = cache.get(id);
  if (!previous) {
    return;
  }

  const next = { ...previous, done: true };
  cache.set(id, next);
  render();

  const response = await fetch(`/api/tasks/${id}`, {
    method: 'PATCH',
    headers: { 'If-Match': String(previous.version) },
    body: JSON.stringify({ done: true }),
  }).catch(() => undefined);

  if (!response) {
    queue.push(next); // Offline: replay later, somehow.
  } else if (response.status === 412) {
    cache.set(id, previous); // Conflict: drop the user's edit?
    render();
  }
};

ECHO

const finish = (id: string) => {
  const task = db.getObjectById<Task>(id);
  if (task) {
    Obj.update(task, (task) => {
      task.done = true;
    });
  }
};

The ECHO version has no error branches for these cases because the failures do not reach it. There is no request to fail, the local write cannot conflict with itself, and a concurrent edit from a peer merges as a CRDT change.

Solving practical problems

Your UI never shows stale local state

Each query reads one local engine, which answers from the objects this tab holds. A subscriber sees your own write in the same call that made it, so a list does not need an optimistic copy of itself. org.dxos.echo.query#F-2

A query can see more than this device holds

Queries also read the host index and EDGE, which hold objects this tab has not loaded. ECHO treats those answers as evidence. It re-evaluates each remote entry against the local document and drops the entry when local state contradicts it, so a slow server cannot bring back an object you deleted. org.dxos.echo.query#F-5

Your types can change after you ship

Every type carries a version in its DXN. An object migration declares how objects of an old version become the new one, so data written by last year’s build still opens. org.dxos.echo#Migration

Your graph is not limited to one document

A Ref field stores a DXN and resolves lazily, across objects and across spaces. Relations are objects too, with typed source and target endpoints, so you can query from either end. org.dxos.echo#F-4

Enjoy building

Once persistence and merging are the database’s job, the code that remains is your application. Start with the learning path, or look up a module in the reference.