Short answer: Global memory holds swarm-wide playbooks and constraints; local memory holds specialist or site notes that would drown everyone if broadcast.
One shared pool creates noise and wrong retrieval; pure private notebooks block coordination. Engram separates layers with groups, project-wide topics, and property scopes. Search global for policy, then local for detail. Graduate local lessons to global only when scrubbed and stable.
Agent swarms collapse when every specialist dumps every thought into one shared pool. They also collapse when each agent keeps a private notebook that nobody else can read. Global memory is the institutional layer every agent may consult for playbooks, ratified facts, and swarm-wide constraints. Local memory is the specialist layer that holds working notes, role-private observations, and feeder-specific detail that would drown the swarm if it were broadcast. This chapter draws that line clearly, shows why swarms need both layers at once, and demonstrates how Weaviate Engram models global versus local memory with separate groups, project-wide topics, and property-scoped searches.
Why Does a Single Shared Pool Fail a Swarm?
A swarm looks efficient when one vector store holds everything. Dispatch agents, sensor agents, and human-facing agents all write into the same bag. Retrieval then returns a mix of policy, gossip, and unfinished drafts. The next agent sounds informed while acting on noise. Shared memory without scope is not collaboration. It is contamination.
Full isolation fails the other way. Each agent remembers only its own turns. The swarm rediscovers the same outage rule ten times. Handoffs become transcript dumps again. You need a middle design. Publish what every agent must know. Keep private what only one role should carry.
Think of a community solar microgrid during a cloudy afternoon. Every inverter agent needs the same curtailment rule. Only the west-feeder agent needs the noisy telemetry from inverter I-17. Global memory carries the rule. Local memory carries the feeder scratch.
What Belongs in Global Memory Versus Local Memory?
Once the failure modes are clear, selection becomes the hard part. Global memory should hold durable, swarm-safe knowledge. Operating procedures. Safety limits that must not drift per agent. Ratified incident lessons. Facts that remain true no matter which specialist is on duty. If publishing a memory would confuse an unrelated role, it is not global.
Local memory should hold role and site specificity. Working hypotheses. Partial measurements. Draft plans that may be wrong. Notes tied to one feeder, one match, or one customer thread. Local memory can be messier because fewer agents read it. That mess stays useful only if scope keeps it away from the global search path.
A practical test helps. Ask whether a brand-new agent joining the swarm should see the fact on day one. If yes, it is a global candidate. Ask whether two agents in the same role on different feeders should share it. If no, keep it local with a property such as feeder_id. Swarms get healthier when that test is boring and repeated.
How Does Weaviate Engram Separate Global and Local Layers?
Knowing the split still leaves implementation. Weaviate Engram maps the layers onto groups and scopes. A project-wide topic needs no user_id. Every agent searching that group can retrieve the same procedural memories. A user-scoped or property-scoped topic isolates local work. You can also use separate groups so global playbooks never share a topic namespace with feeder scratchpads.
In practice, many swarms use two groups. One group holds continual operational learning that is project-wide. Another holds feeder-local notes scoped by properties such as feeder_id, often with an agent id as user_id when the note is role-private. Agents search global first for policy. They search local second for site detail. Hybrid retrieval works well for both queries.
Here is a microgrid dispatch swarm writing a global curtailment lesson and a local west-feeder observation:
import os
from engram import EngramClient, HybridRetrieval
client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
feeder = "feeder-west-14"
# Global playbook: project-wide group, no user_id required for project-wide topics
global_run = client.memories.add(
"On low irradiance afternoons, curtail feeder export before battery SOC drops below 25 percent. "
"Never override the soft export cap without dispatcher approval.",
group="grid_playbook",
)
client.runs.wait(global_run.run_id)
# Local scratch: scoped to one feeder and one specialist agent
local_run = client.memories.add(
"Inverter I-17 on feeder-west-14 is oscillating reactive power. "
"Treat readings as provisional until the next calibration window.",
user_id="agent-inverter-west",
group="feeder_local",
properties={"feeder_id": feeder},
)
client.runs.wait(local_run.run_id)
# Dispatch agent loads institutional rules, then site-specific noise
policy = client.memories.search(
query="export curtailment battery SOC soft cap rules",
group="grid_playbook",
retrieval_config=HybridRetrieval(limit=5),
)
site = client.memories.search(
query="reactive power oscillation inverter trustworthiness",
user_id="agent-inverter-west",
group="feeder_local",
properties={"feeder_id": feeder},
retrieval_config=HybridRetrieval(limit=5),
)
The dispatch agent never confuses a provisional inverter note with a ratified curtailment rule. Different groups enforce that separation even when the query text overlaps. That is the operational meaning of global versus local memory in Engram.
When Should Local Memories Graduate Into Global Memory?
The code shows two layers. Swarms still need a promotion path. A local observation that keeps recurring across feeders is no longer local. Promote it deliberately. Write a clean global memory in the playbook group. Leave the original local notes in place for provenance, or mark them superseded in local scope if your topics support bounded status memories.
Do not auto-promote every frequent string. Promotion is a governance act. Someone or some review agent decides the lesson is safe for the whole swarm. Until then, keep it feeder-local. Premature global writes teach every agent a half-true rule.
Demotion matters too. A global rule that only ever applied to one experimental feeder should move back to local scope. Search quality improves when the global layer stays short and trusted. Swarms scale on trust more than on volume.
How Do You Keep Swarm Searches From Crossing the Wrong Layer?
After promotion rules exist, retrieval discipline finishes the design. Framework wrappers should expose two calls, not one. Search global playbook. Search local scope. Concatenate results with clear labels in the prompt so the model knows which layer each fact came from. A single undifferentiated search across both groups invites the contamination problem again.
Also be strict about write paths. Sensor agents write local by default. Only a designated learning or dispatcher path writes global. That matches Engram’s group isolation. It also matches how real operations teams separate logs from standing orders.
When an agent must see local notes from a peer role on the same feeder, share the feeder property without sharing the peer’s private user id. Configure topics so feeder-scoped operational notes are readable by the dispatch role, while true private scratch remains user-scoped to the writer. Soft property isolation and hard user isolation give you that mix without inventing a second store.
Our next chapter, How do you synchronize memory across long-running agent sessions?, asks what happens when those global and local layers must stay coherent for hours or days as agents sleep, resume, and rejoin the swarm.