How do you partition memory by agent role?

Shared memory helps a team of agents stay aligned. It does not mean every specialist should read every specialist’s notes. Roles exist because different jobs need different context. A picker needs path rules. A temperature monitor needs sensor thresholds. Dumping both into one prompt wastes tokens and invites the wrong agent to act on the wrong detail. Memory partitioning by agent role is the practice of giving each role a shaped store, and routing retrieval so each agent sees what its job requires. This chapter explains why that partition matters, how to design it, and how Weaviate Engram uses groups, topics, and scoped search to keep role memories separate without losing optional shared lessons.

Why Should Different Agent Roles Keep Different Memories?

Roles create different questions. The irrigator asks when to water. The harvester asks which rows are ready. Those questions pull on different histories. If both agents search one undifferentiated pile, each prompt fills with near-misses from the other role. Quality drops even when the store contains the right facts.

Research on role-aware routing makes the cost visible. Full-context sharing across agents burns tokens on redundant exposure. Static routing that always sends the same packet is only slightly better. Better systems select memory subsets by role and task stage. Heterogeneous agents also need heterogeneous memories so each role keeps its own perspective instead of converging on one blended summary.

Partitioning is therefore not just an access-control story. It is a clarity story. Narrow memory keeps specialists sharp. It also reduces the chance that a tool agent treats a customer preference as an operational instruction, or the reverse.

What Goes Wrong When Every Role Shares One Homogeneous Memory Bank?

Homogenization is the first failure. Over time, retrieval returns the same generic lessons to every agent. Role-specific craft disappears. The team looks coordinated and acts vague.

Information overload is the second failure. Fine-grained traces from every role accumulate in one index. Similarity search surfaces fragments that are related in language but useless for the current job. Agents then either ignore memory or overfit to noise.

Procedural drift is the third failure. An orchestrator may need plan-level memory. A tool agent may need execution-level memory. Mixing those layers makes the orchestrator micromanage from tool noise, while the tool agent invents policy from partial plans. Partitioning by role keeps those layers readable.

How Do You Design Partitions That Match Real Roles?

Start from the verbs each agent owns. Write verbs, verify verbs, move verbs, and talk-to-user verbs rarely need identical stores. Give each role a memory group whose topics describe only what that role should extract. Topic descriptions are magnets. If the picker’s topics never mention sensor calibration, calibration chatter is less likely to become pick-path memory.

Decide what stays private to the role and what may be promoted to a shared team store. Role partitions hold craft. Shared continual-learning partitions hold scrubbed house rules. Property scopes can further slice a role’s memory by bay, lot, or shift without merging roles together.

At read time, route deliberately. The application should search the role’s group first. It may also search a small shared group when the task needs house rules. It should not “just in case” merge every group into every prompt. Role-aware retrieval is part of the product, not an afterthought filter.

How Does Weaviate Engram Enforce Role Partitions in Practice?

Weaviate Engram maps roles cleanly onto groups. Each group is a use-case bundle of topics and a pipeline. Memories in one group are isolated from other groups through multi-tenancy. Two agents can even reuse the same topic name in different groups without collision. That lets a procedures topic mean irrigation procedures in one group and harvest procedures in another.

Within a group, topics refine the partition further. Searching with an explicit topic list returns only the slice that role needs right now. Scopes still apply. Project-wide topics share trusted craft inside that role’s group. User-scoped topics keep any person-specific facts sealed when a role must handle them.

Here is a vertical-farm example. An irrigation agent and a harvest agent work the same tower row, but they write and read different Engram groups:

from engram import EngramClient, HybridRetrieval

client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
row_id = "tower-row-12"

# Irrigation role: only watering craft in its own group.
client.memories.add(
    "For tower-row-12 leafy greens, drip for 90 seconds after canopy temp exceeds 27C.",
    group="irrigation_ops",
    properties={"row_id": row_id},
)

# Harvest role: only readiness craft in a separate group.
client.memories.add(
    "Harvest outer leaves on tower-row-12 only after the third true-leaf flush.",
    group="harvest_ops",
    properties={"row_id": row_id},
)

irrigator_context = client.memories.search(
    query="Should I water tower-row-12 this cycle?",
    group="irrigation_ops",
    properties={"row_id": row_id},
    retrieval_config=HybridRetrieval(limit=5),
)

harvester_context = client.memories.search(
    query="Which leaves are ready on tower-row-12?",
    group="harvest_ops",
    properties={"row_id": row_id},
    retrieval_config=HybridRetrieval(limit=5),
)

The irrigator never receives harvest flush rules unless the product explicitly searches that group. The harvester never receives drip timings by accident. Optional shared house rules can still live in a third continual_learning group that both roles query when policy truly applies to everyone.

When Should a Role Still Reach Outside Its Partition?

Partitions are defaults, not walls against coordination. An orchestrator may need a thin summary from each role to plan the next step. A safety agent may need read access across roles when a threshold is breached. Those cross-reads should be narrow, logged, and purposeful.

Promotion remains the safe path for lasting cross-role knowledge. If irrigation discovers a rule that harvest must obey, do not grant harvest free range over irrigation traces. Write a scrubbed shared memory into the team store. Keep the detailed sensor diary inside irrigation_ops.

Review partitions as roles evolve. New tools often imply new memory shapes. If a role’s prompt keeps asking for facts that live elsewhere, either widen that role’s topics carefully or add an explicit shared slice. Do not dissolve the partition just because one workflow felt inconvenient once.

Once each role has a place to write, concurrent updates become the next hazard. Two agents can race to record conflicting lessons about the same job. Our next chapter, How do you coordinate memory writes from multiple agents?, turns to write coordination, conflict, and safe commit patterns across the team.