fix: prevent delegated sub-agent messages from polluting supervisor m…

[omeraplak]

…emory context

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

What is the new behavior?

fixes (issue)

• [BUG] Sub-agent with memory writes duplicate messages to parent conversation history via delegate_task #1026

Notes for reviewers

---

Summary by cubic

Prevents delegated sub-agent messages from showing up in the supervisor’s memory, keeping parent prompts clean while preserving sub-agent records for debugging. Fixes Linear #1026.

• Bug Fixes
  • Tag delegated sub-agent messages with metadata: subAgentId, subAgentName, parentAgentId.
  • Filter memory reads (getMessages/search/fetch) to exclude delegated sub-agent records not from the current agent.
  • Keep shared conversationId behavior unchanged.
  • Add tests for metadata + filtering and update memory/subagent docs.

^{Written for commit 9a259c6. Summary will update on new commits.}

Summary by CodeRabbit

Release Notes

• New Features

  • Delegated sub-agent messages now automatically tagged with metadata to support observability and debugging across multi-turn handoffs.
  • Supervisor conversation context automatically filtered to exclude delegated sub-agent messages, maintaining cleaner context during delegation workflows.

• Documentation

  • Updated memory and sub-agent documentation to reflect new message tagging behavior.

[changeset-bot]

🦋 Changeset detected

Latest commit: 9a259c6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@voltagent/core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces metadata tagging for delegated sub-agent messages containing subAgentId, subAgentName, and parentAgentId. Updates memory manager to filter delegated messages from supervisor conversation context during reads while preserving them with metadata for observability.

Changes

Cohort / File(s)	Summary
Changelog .changeset/cruel-trains-cut.md	Documents behavioral change for delegated sub-agent message metadata tagging and supervisor memory filtering.
Sub-agent Delegation packages/core/src/agent/subagent/index.ts	Augments delegated task messages with metadata containing subAgentId, subAgentName, and parentAgentId for routing context.
Memory Manager Implementation packages/core/src/memory/manager/memory-manager.ts	Adds delegation metadata propagation in applyOperationMetadata; introduces resolveDelegationMetadata and filterDelegatedSubAgentMessages helpers; integrates filtering into getMessages, searchMessages, and prepareConversationContext retrieval paths to exclude delegated sub-agent records from supervisor context.
Test Coverage packages/core/src/memory/manager/memory-manager.spec.ts	Validates delegation metadata recording (operationId, parentAgentId, subAgentId, subAgentName) and filtering of delegated messages from parent conversation context.
Documentation website/docs/agents/memory/overview.md, website/docs/agents/subagents.md	Notes metadata tagging behavior for delegated messages and supervisor memory filtering capabilities.

Sequence Diagram

sequenceDiagram
    participant Supervisor as Supervisor Agent
    participant SubAgent as Sub-Agent
    participant MemMgr as Memory Manager
    participant Store as Message Store
    
    Supervisor->>SubAgent: delegate_task (with delegationContext)
    SubAgent->>MemMgr: writeMessage (delegated task)
    MemMgr->>MemMgr: applyOperationMetadata<br/>(add subAgentId, parentAgentId)
    MemMgr->>Store: save message with metadata
    
    SubAgent->>Store: process & respond
    SubAgent->>MemMgr: writeMessage (sub-agent response)
    MemMgr->>Store: save with delegation metadata
    
    Supervisor->>MemMgr: getMessages (supervisor context)
    MemMgr->>Store: retrieve all messages
    MemMgr->>MemMgr: filterDelegatedSubAgentMessages<br/>(remove delegated records)
    MemMgr->>Supervisor: return filtered context<br/>(only supervisor messages)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [BUG] Sub-agent with memory writes duplicate messages to parent conversation history via delegate_task #1026: Directly addresses duplicate delegated-message handling by introducing metadata tagging (subAgentId/subAgentName/parentAgentId) and filtering delegated records from supervisor memory context.

Poem

🐰 A delegate hops with metadata care,
Sub-agents tagged in the memory air,
Filters cleanse what the supervisor sees,
While delegation trails persist with ease!
Hops of clarity, observability's prize! 🌟

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: preventing delegated sub-agent messages from polluting supervisor memory context, which aligns with the changeset's primary objective.
Description check	✅ Passed	The description is mostly complete, covering all required sections: checklist items are checked, current/new behavior is addressed, related issues are linked, and comprehensive auto-generated summary explains the changes with specific implementation details.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/subagent-memory-filter

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/core/src/memory/manager/memory-manager.ts (1)

234-267: resolveDelegationMetadata: Use direct symbol key lookup instead of iterating all systemContext values.

The method iterates through all systemContext values and breaks on the first object with either agentId or agentName (line 257). This is inefficient and fragile — if systemContext ever contains other objects with these fields, the lookup will return incorrect results or incomplete metadata.

The codebase already establishes a pattern of direct symbol key lookup elsewhere (e.g., subagent/index.ts:924, memory-persist-queue.ts:109). Import AGENT_METADATA_CONTEXT_KEY from @voltagent/internal or the appropriate package and replace the loop with:

const agentMetadata = context.systemContext.get(AGENT_METADATA_CONTEXT_KEY) as
  | AgentMetadataContextValue
  | undefined;

This matches the established pattern, guarantees only the expected metadata structure is retrieved, and is more efficient.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 6 files

[cloudflare-workers-and-pages]

Deploying voltagent with    Cloudflare Pages

Latest commit:	9a259c6
Status:	✅  Deploy successful!
Preview URL:	https://5f6cdf1a.voltagent.pages.dev
Branch Preview URL:	https://fix-subagent-memory-filter.voltagent.pages.dev

View logs