Multi-Agent Memory Sharing Guide¶

ALMA supports hierarchical memory sharing between agents, enabling knowledge transfer without duplicating data.

Overview¶

Multi-agent sharing allows: - Senior agents to share knowledge with juniors - Specialized agents to contribute domain expertise - Team leads to propagate best practices - Cross-functional teams to collaborate

Configuration¶

share_with¶

Makes your memories readable by other agents.

agents:
  senior_developer:
    domain: coding
    can_learn:
      - architecture
      - best_practices
      - design_patterns
    share_with:
      - junior_developer
      - qa_engineer

inherit_from¶

Allows reading memories from other agents.

agents:
  junior_developer:
    domain: coding
    can_learn:
      - coding_patterns
      - debugging
    inherit_from:
      - senior_developer
      - tech_lead

Complete Example¶

alma:
  project_id: "my-team"
  storage: sqlite

agents:
  # Tech lead shares with everyone
  tech_lead:
    domain: coding
    can_learn:
      - architecture
      - system_design
      - team_standards
    share_with:
      - senior_developer
      - junior_developer
      - qa_engineer
      - devops_engineer

  # Senior dev shares with juniors, learns from lead
  senior_developer:
    domain: coding
    can_learn:
      - implementation_patterns
      - code_review
    inherit_from:
      - tech_lead
    share_with:
      - junior_developer

  # Junior learns from senior and lead
  junior_developer:
    domain: coding
    can_learn:
      - basic_patterns
      - debugging
    inherit_from:
      - senior_developer
      - tech_lead

  # QA learns from tech lead
  qa_engineer:
    domain: testing
    can_learn:
      - testing_strategies
      - bug_patterns
    inherit_from:
      - tech_lead

Usage in Code¶

Retrieving Shared Memories¶

from alma import ALMA

alma = ALMA.from_config(".alma/config.yaml")

# Junior developer retrieves memories
# This includes their own + senior_developer + tech_lead memories
memories = alma.retrieve(
    task="Implement user authentication",
    agent="junior_developer",
    include_shared=True,  # Enable shared memory retrieval
    top_k=10
)

# Access all heuristics (own + inherited)
for heuristic in memories.heuristics:
    if heuristic.metadata.get('shared_from'):
        # This memory came from another agent
        origin = heuristic.metadata['shared_from']
        print(f"[From {origin}] {heuristic.strategy}")
    else:
        # This is the agent's own memory
        print(f"[Own] {heuristic.strategy}")

Checking Memory Origin¶

# Filter to only inherited memories
inherited = [
    h for h in memories.heuristics
    if h.metadata.get('shared_from')
]

# Filter to only own memories
own = [
    h for h in memories.heuristics
    if not h.metadata.get('shared_from')
]

print(f"Own memories: {len(own)}")
print(f"Inherited memories: {len(inherited)}")

Learning Still Respects Scope¶

When an agent learns, the memory is stored under their own agent ID, not the inherited agent's:

# Junior learns from their experience
alma.learn(
    agent="junior_developer",
    task="Fixed null pointer bug",
    outcome="success",
    strategy_used="Added null checks before dereferencing"
)
# This memory belongs to junior_developer
# It will be shared with NO ONE (junior has no share_with)

How It Works¶

Retrieval Flow¶

Agent requests memories with include_shared=True
ALMA looks up agent's scope for inherit_from list
For each inherited agent, ALMA checks their share_with includes requesting agent
Valid inherited agents are added to the query
Single optimized query retrieves from all agents
Results are marked with shared_from metadata

Permission Model¶

Both conditions must be met for sharing: 1. Receiver lists source in inherit_from 2. Source lists receiver in share_with

This prevents unauthorized access:

agents:
  alice:
    share_with: [bob]  # Alice shares with Bob

  bob:
    inherit_from: [alice]  # Bob can read Alice's memories ✓

  charlie:
    inherit_from: [alice]  # Charlie tries to read Alice
    # DENIED - Alice doesn't have charlie in share_with

Optimized Queries¶

ALMA uses optimized batch queries for multi-agent retrieval:

# Instead of N separate queries
for agent in agents_to_query:
    results.extend(storage.get_heuristics(agent=agent))

# ALMA uses one query with OR conditions
results = storage.get_heuristics_for_agents(
    agents=agents_to_query,  # Single query for all
    ...
)

Patterns¶

Expertise Hierarchy¶

agents:
  domain_expert:
    can_learn: [deep_domain_knowledge]
    share_with: [generalist_1, generalist_2]

  generalist_1:
    inherit_from: [domain_expert]

  generalist_2:
    inherit_from: [domain_expert]

Team Structure¶

agents:
  team_lead:
    share_with: [member_1, member_2, member_3]

  member_1:
    inherit_from: [team_lead]
    share_with: [member_2, member_3]  # Peer sharing

  member_2:
    inherit_from: [team_lead, member_1]
    share_with: [member_1, member_3]

Mentor-Mentee¶

agents:
  mentor:
    share_with: [mentee]

  mentee:
    inherit_from: [mentor]
    # Mentee doesn't share back - one-way knowledge transfer

TypeScript SDK¶

import { ALMA } from 'alma-memory';

const alma = new ALMA({
  baseUrl: 'http://localhost:8765',
  projectId: 'my-team'
});

// Retrieve with shared memories
const memories = await alma.retrieve({
  query: 'implement authentication',
  agent: 'junior_developer',
  topK: 10,
  includeShared: true
});

// Check origin
memories.heuristics.forEach(h => {
  if (h.metadata?.shared_from) {
    console.log(`Learned from ${h.metadata.shared_from}: ${h.strategy}`);
  }
});

Best Practices¶

Keep hierarchies shallow - Deep inheritance chains can be confusing
Be explicit about sharing - Both share_with and inherit_from are required
Don't over-share - Only share what's relevant to the receiver
Monitor inherited memory counts - Too many can dilute relevance
Use meaningful agent names - Makes shared_from metadata readable

Troubleshooting¶

No inherited memories appearing¶

Check: 1. include_shared: true is set in retrieve call 2. Source agent has receiver in share_with 3. Receiver agent has source in inherit_from 4. Source agent actually has memories

Too many inherited memories¶

Reduce top_k value
Be more specific in your query
Review if all inherited agents are necessary

Performance concerns¶

Multi-agent queries are optimized, but with many agents: - Consider caching results - Use appropriate top_k limits - Review if full inheritance chain is needed