What is federated memory across independent agent deployments?

Independent agent deployments rarely share one memory database, and they should not. Different regions, brands, and legal entities keep their own Engram projects for good reasons. Federated memory is the disciplined practice of sharing only selected lessons across those boundaries while leaving private case data local. This chapter explains why naive shared stores fail across organizations, what is safe to federate versus what must stay home, how Weaviate Engram’s project and group isolation makes local memory the default, and how an export-import ritual can move sanitized playbook memories between deployments without opening a back door into customer data.

Why Can’t Independent Deployments Just Share One Memory Pool?

A single pool looks efficient on a whiteboard. In production it collides with tenancy, regulation, and trust. One marina’s guest preferences must never appear in another marina’s agent context. One region’s outage notes may contain vendor contracts the peer region is not allowed to see. Merging projects to “make collaboration easier” is how leaks become features.

Framework-level shared state also fails across deployments. Those shared objects usually live inside one runtime. Federation needs durable memory that survives separate clouds, separate API keys, and separate release schedules. The units of cooperation are messages and curated memories, not a mutual filesystem.

So the design goal is not total visibility. It is selective continuity. Each deployment remains sovereign. A narrow channel carries only memories that have been approved for export.

What Is Safe to Federate, and What Must Stay Local?

Once sovereignty is the default, selection becomes the hard work. Safe federation candidates are procedural and de-identified. Storm mooring sequences. Equipment failure patterns with serial numbers removed. Playbook steps that remain true in both harbors. If a memory names a guest, a slip holder, or a private berth dispute, it stays local.

Local memory keeps case files, personalization, and region-specific constraints. Those records use user scopes and property scopes inside the home Engram project. Federation never searches another project’s user-scoped topics. It only receives content that an exporter deliberately wrote as shareable lesson text.

A useful test is replay under audit. Could you show a regulator exactly which memories crossed the boundary and which did not? If the answer depends on hope, the channel is too wide. Tag federated writes with source deployment ids in the text or properties so provenance survives the hop.

How Does Weaviate Engram Keep Deployments Isolated by Default?

The selection rules need a store that refuses accidental sharing. Weaviate Engram binds every memory to a project through the API key. Groups further isolate use cases with multi-tenancy. User-scoped topics enforce hard separation between people. That stack means two independent marina deployments do not see each other unless your application copies content on purpose.

Inside one deployment, keep local operations in one group and federated playbooks in another. Local agents search both. Remote peers never receive credentials to the local group. The federation job authenticates to each project separately, reads only from an export-approved topic or search filter, and writes sanitized strings into the peer’s federated group.

Here is a two-marina federation hop that exports a storm lesson from East Harbor into West Harbor’s playbook group without sharing guest data:

import os
from engram import EngramClient, HybridRetrieval

east = EngramClient(api_key=os.environ["ENGRAM_EAST_API_KEY"])
west = EngramClient(api_key=os.environ["ENGRAM_WEST_API_KEY"])

# Local incident stays in East Harbor only
local = east.memories.add(
    "Slip B-12 guest reported frayed bow line before the squall. "
    "Replaced line on site. Do not share guest identity outside East Harbor.",
    user_id="dockmaster-east",
    group="marina_local",
    properties={"incident_id": "east-squall-19"},
)
east.runs.wait(local.run_id)

# Curated exportable lesson written in East's federated outbox group
exportable = (
    "Before forecast squalls above 35 knots, double bow lines on exposed finger piers "
    "and stage spare cleats at the head of each fairway. "
    "Source deployment: marina-east."
)
outbox = east.memories.add(
    exportable,
    group="federated_outbox",
)
east.runs.wait(outbox.run_id)

# Federation worker reads East outbox, writes into West playbook project
candidates = east.memories.search(
    query="squall bow lines finger piers spare cleats",
    group="federated_outbox",
    retrieval_config=HybridRetrieval(limit=3),
)

for memory in candidates:
    run = west.memories.add(
        memory.content,
        group="federated_playbook",
        properties={"origin": "marina-east", "transfer_id": "fed-batch-88"},
    )
    west.runs.wait(run.run_id)

# West agent uses local context plus federated playbook
west_local = west.memories.search(
    query="current open work orders on north basin",
    user_id="dockmaster-west",
    group="marina_local",
    retrieval_config=HybridRetrieval(limit=4),
)
west_fed = west.memories.search(
    query="squall mooring double bow lines finger piers",
    group="federated_playbook",
    retrieval_config=HybridRetrieval(limit=4),
)

East’s guest note never crosses. Only the curated outbox text does. West keeps its own API key and its own local group. That is federation with Engram rather than a merged brain.

How Should Federation Jobs Handle Conflict and Stale Lessons?

After the hop works once, conflict appears. East may revise a playbook that West already imported. Do not silently overwrite peer memory from a blind sync. Write a new federated memory that states the revision and the transfer id. Let West’s transform and dedup behavior reconcile within West’s project. Each deployment remains authoritative for what it believes.

Revocation matters too. If East discovers the lesson was wrong, publish a superseding federated note rather than asking West to delete by remote id. Remote deletes across organizational boundaries are fragile. Explicit supersession text survives audits better.

Rate the channel. Federation should be batchy and reviewed, not a firehose of every local write. Many teams require a human or policy agent to promote a memory into federated_outbox. That promotion step is the real security boundary.

What Operating Model Keeps Federated Memory Trustworthy Over Time?

Conflict rules still need people and metrics. Maintain a catalog of which groups are exportable. Rotate API keys per deployment. Log every transfer id. Periodically search each peer playbook for origin tags and confirm the contents still match policy.

Measure usefulness, not just volume. If federated memories never appear in successful agent traces, the channel is noise. If local private data ever appears in a peer search, the channel is a breach. Both signals should page operators.

Federated memory succeeds when independence remains obvious and cooperation remains deliberate. Engram gives each deployment a sealed project. Your federation layer chooses the few sentences worth copying. That combination scales across harbors, brands, and legal walls without pretending they are one system.

Our next chapter, Why do memory systems need their own evaluation framework?, leaves multi-agent architecture and asks how to measure whether memory is actually helping, not merely filling up.