Docs/Multi-agent memory

Example

Multi-agent memory

Build a fleet where research and writing workers keep local context, read shared knowledge, and transfer selected memory through a conductor.

Estimated time: 15 minutes

Level: Advanced

Prerequisites:Installation·Quick Start·Fleet & Shared Memory·Grafting Memory

Overview

This example creates a research worker, a writing worker, shared fleet guidance, and a conductor. Research remains local until the conductor deliberately transfers selected context into the writer.

What this demonstrates

Worker-local and shared fleet memory.

Worker memory modes.

Conductor-led semantic transfer.

Transferred-memory provenance.

The difference between shared reads and copied grafts.

Architecture

Research worker

Conductor transfer

Writing worker

Shared fleet policy

Memory design

Research worker: source findings and unresolved questions.

Writing worker: outline decisions, tone, and draft-specific context.

Shared fleet memory: editorial policy or project-wide constraints.

Conductor: explicit selection and transfer between worker graphs.

Graft registry: source session and source node provenance for copied topics.

Step 1: Create the fleet and workers

fleet.ts

const fleet = new MemoGrafterFleet(config, {
  id: "research-fleet",
  name: "Research and Writing",
});

await fleet.initialize();

const conductor = fleet.createConductor();
const researcher = await fleet.createWorker({
  color: "research",
  memory: "both",
});
const writer = await fleet.createWorker({
  color: "writer",
  memory: "both",
});

Step 2: Add shared guidance

shared-memory.ts

await fleet.ingestToFleet(
  "Editorial rule: distinguish sourced claims from interpretation.",
  {
    tags: ["editorial-policy"],
    source: "editorial-handbook",
  },
);

Step 3: Build research memory

research.ts

await researcher.invoke(
  "The study reports higher retrieval precision with confidence weighting.",
);
await researcher.invoke(
  "Its main limitation is a small evaluation set.",
);

Step 4: Transfer selected context

transfer.ts

const copied = await conductor.graftByPrompt(
  "retrieval findings and limitations",
  writer,
  {
    minSimilarity: 0.55,
    limit: 4,
  },
);

console.log("Copied topics:", copied.length);

Step 5: Write with local and shared memory

write.ts

const answer = await writer.invoke(
  "Draft a concise paragraph describing the result and its limitation.",
);

console.log(answer);

Complete example

src/multi-agent-memory.ts

import "dotenv/config";

import {
  MemoGrafterFleet,
  OpenAIEmbedAdapter,
  OpenAILLMAdapter,
} from "memo-grafter";

const config = {
  db: { connectionString: process.env.DATABASE_URL! },
  llm: new OpenAILLMAdapter("gpt-4o"),
  embedder: new OpenAIEmbedAdapter("text-embedding-3-small"),
};

const fleet = new MemoGrafterFleet(config, { id: "research-fleet" });
await fleet.initialize();

try {
  const conductor = fleet.createConductor();
  const researcher = await fleet.createWorker({
    color: "research",
    memory: "both",
  });
  const writer = await fleet.createWorker({
    color: "writer",
    memory: "both",
  });

  await fleet.ingestToFleet(
    "Editorial rule: distinguish sourced claims from interpretation.",
    { tags: ["editorial-policy"], source: "editorial-handbook" },
  );

  await researcher.invoke(
    "The study reports higher precision with confidence weighting.",
  );
  await researcher.invoke(
    "Its main limitation is a small evaluation set.",
  );

  await conductor.graftByPrompt(
    "retrieval findings and limitations",
    writer,
    { minSimilarity: 0.55, limit: 4 },
  );

  console.log(
    await writer.invoke(
      "Draft a concise paragraph describing the result and limitation.",
    ),
  );
} finally {
  await fleet.close();
}

Expected behavior

The researcher’s original conversation remains in its local worker session.

The writer receives only topics selected by the conductor prompt.

The writer can also read the shared editorial policy because its memory mode is both.

The response should mention the retrieval result and limitation while following the shared editorial rule.

Shared recall versus grafting

Shared fleet recall reads knowledge from the synthetic fleet session without copying it into the worker.

Conductor grafting copies selected topic and active memory nodes into the target worker.

Copied nodes receive fresh IDs and registry provenance.

Use shared memory for common knowledge and grafting for deliberate worker-to-worker transfer.

What gets stored

Fleet metadata and registered worker identities.

Shared editorial policy in the fleet session.

Research conversation and extracted memory in the research worker session.

Copied research topics and active memories in the writer session.

Graft registry entries and grafted edges preserving source provenance.

Inspect it in Studio

Inspect the shared fleet session for the editorial policy.

Inspect the research worker for the original findings.

Inspect the writer for copied topics and graft provenance.

Use Prompt Preview on the writer’s draft query.

Confirm inactive source memories were not copied.

Production considerations

Authorize cross-worker transfer before conductor operations.

Keep private worker context out of shared fleet memory.

Use deliberate worker colors; conductor is reserved.

Monitor ingestion completion before initiating transfer.

Close the fleet once during graceful shutdown.

Common mistakes

Assuming all worker memory is automatically shared.

Using a fleet policy session for private task context.

Confusing a shared read with a copied graft.

Transferring all research topics without preview or relevance limits.

Ignoring registry provenance after transfer.

Extensions

Add a reviewer worker with shared editorial memory.

Transfer only source-verified findings to the writer.

Inspect and remove a graft after the writing task.

Add project tags and separate fleets for tenant isolation.