Short answer: Orchestrators store plan and routing lessons; sub-agents store craft execution lessons—in separate Engram groups so they do not contaminate each other.
One shared bank drowns planners in tool noise and gives specialists unusable strategy notes. Search the matching layer first; cross-read only for a reason. Keep handoffs thin: compact outcomes up, clear subgoals down. Promote scrubbed lessons between layers deliberately, not by dumping diaries.
Hierarchical agent teams split work on purpose. An orchestrator plans, decomposes, and delegates. Sub-agents execute narrow tool loops. If those layers share one undifferentiated memory pile, the planner drowns in tool noise and the specialist inherits half-baked strategy notes it cannot use. Sub-agent memory and orchestrator memory are different products. One stores how to decompose and route work. The other stores how to execute a craft step well. This chapter separates those layers, explains what belongs in each, and shows how Weaviate Engram uses isolated groups and scoped search so planners and specialists improve without contaminating each other.
What Does an Orchestrator Need to Remember That a Sub-Agent Does Not?
Orchestrator memory is about the whole job. It remembers successful plan shapes, which specialist to call for which symptom, when to replan, and which handoff packets were too thin. It is full-task procedural memory. Research on modular multi-agent memory finds this layer especially important. Without it, decomposition and delegation stay weak even when specialists are strong.
Sub-agent memory is local. It remembers tool argument patterns, validation checks, and recovery steps for one craft. A zoning checker needs setback rules and GIS query habits. It does not need the orchestrator’s debate about whether to call legal review before or after parking analysis.
Mixing those layers creates procedural drift in both directions. The orchestrator starts micromanaging from densitometer-level traces. The sub-agent starts inventing policy from partial plans. Clear separation keeps each prompt at the right altitude.
Why Does One Shared Memory Bank Hurt Hierarchical Teams?
Similarity search does not know your org chart. A query about “how we handled the last difficult package” can return an orchestrator reflection and a specialist tool dump with equal confidence. Both may be relevant in language. Only one is useful for the current role.
Shared banks also create write pollution. Sub-agents produce high-volume traces. Orchestrators produce fewer, denser planning notes. Volume wins retrieval unless partitions and topics restrain it. The planner then looks busy and learns little about routing.
Promotion still matters. A specialist discovery that changes how work should be sequenced belongs in orchestrator memory only after it is scrubbed into a plan-level lesson. Raw tool success is not automatically a delegation rule. Engram groups make that promotion an explicit write into another use case, not an accident of one index.
How Should You Partition Orchestrator and Sub-Agent Stores?
Give the orchestrator its own group whose topics describe plans, delegation choices, and replanning triggers. Give each specialist family a group whose topics describe actions, tool outcomes, and local constraints. Groups in Engram are isolated with multi-tenancy, so topic names can even repeat without collision. A procedures topic in orchestrator_memory is not the same object space as procedures in zoning_ops.
Scope both layers by the same job identifier when you need correlation later. Property scopes such as package_id let you reconstruct a case without merging the banks. The orchestrator searches its group for how to stage the package. The sub-agent searches its group for how to run its step. A separate handoff group can carry the thin status notes between them.
Retrieval policy should follow role. At planning time, load orchestrator memories first. At execution time, load sub-agent memories first. Cross-read only for a reason, such as an orchestrator inspecting a failed specialist outcome summary, not the entire tool diary.
How Does Weaviate Engram Express That Split in Code?
Weaviate Engram’s multi-agent continual-learning pattern already assumes goals, actions, and feedback may arrive from different agents and windows. Hierarchical teams push the same idea further by storing those slices in different groups from the start. The orchestrator writes plan memory. The sub-agent writes action memory. Later searches stay role-true.
Consider a city permit desk processing package permit-pkg-441. The orchestrator decides sequencing. A zoning sub-agent runs setback checks with GIS tools. Each keeps Engram memory at its own altitude.
from engram import EngramClient, HybridRetrieval
client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
package_id = "permit-pkg-441"
props = {"package_id": package_id}
# Orchestrator: plan-level memory only.
client.memories.add(
"For hillside ADU packages, run zoning setbacks before parking variance review.",
group="orchestrator_memory",
properties=props,
)
# Zoning sub-agent: execution-level memory only.
client.memories.add(
"On hillside lots, query the slope overlay before measuring rear setback from the facade line.",
group="zoning_ops",
properties=props,
)
orch_context = client.memories.search(
query="How should I sequence review for this hillside ADU package?",
group="orchestrator_memory",
properties=props,
retrieval_config=HybridRetrieval(limit=5),
)
zoning_context = client.memories.search(
query="How do I measure rear setback on a hillside lot?",
group="zoning_ops",
properties=props,
retrieval_config=HybridRetrieval(limit=5),
)
The orchestrator never receives the slope-overlay tool tip unless the product deliberately searches zoning_ops. The zoning agent never receives sequencing policy from orchestrator_memory by accident. Both can still share package_id when a supervisor needs to audit one case end to end.
When Should Lessons Move Between the Two Layers?
Promotion from sub-agent to orchestrator should answer a planning question. “Always call drainage review when the lot intersects creek buffer” is orchestrator material. “Use layer CREEK_BUF_V3 in the GIS tool” stays in the sub-agent store. Demotion is rarer. If a plan-level rule is really only a tool quirk, move it down so planners stop treating it as strategy.
User-facing personalization usually lives with the orchestrator or a dedicated personalization group, not inside every specialist. Specialists should receive the minimum user constraint required for the subtask. That keeps private detail out of high-volume tool memory.
Evaluate the layers separately. Measure whether the orchestrator routes better over time. Measure whether sub-agents reduce tool retries. A single end-to-end success rate can hide a strong specialist trapped under a weak planner, or the reverse.
Keep the interface between layers thin on purpose. The orchestrator should receive compact specialist outcomes, not entire tool diaries. The sub-agent should receive a clear subgoal and constraints, not the planner’s full deliberation transcript. Memory groups enforce that thinness when the application searches only the group that matches the role.
Separate stores still need agreement about how fresh a read is allowed to be. Distributed agent memory raises consistency questions once many writers and readers are in flight. Our next chapter, What consistency models matter for distributed agent memory?, turns to those guarantees and trade-offs.