feat: add voltagent-level memory

[omeraplak]

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)

Notes for reviewers

---

Summary by cubic

Adds VoltAgent-level default memory so agents and workflows can inherit shared Memory without configuring it on each instance. This makes setup simpler while preserving per-agent/workflow overrides.

• New Features
  • VoltAgent accepts memory, agentMemory, and workflowMemory defaults.
  • Agents and workflows auto-apply defaults when memory is not set. memory: false on an agent disables memory and skips defaults.
  • Precedence: Agents use agent memory > shared memory > built-in in-memory. Workflows use workflow memory > shared memory > built-in in-memory.
  • AgentRegistry stores global memory defaults for agents and workflows.
  • Workflows and agents expose internal setters to apply defaults safely.
  • Docs: added “VoltAgent Instance” guide and updated memory/workflow docs with default configuration and precedence.

^{Written for commit 63ac075. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • VoltAgent supports entrypoint-level default memory: shared, per-agent, and per-workflow defaults with clear precedence; agents/workflows can opt out.

• Documentation

  • New VoltAgent instance guide; updated memory and workflow docs with examples and scoping guidance; docs navigation updated.

• Tests

  • Added tests validating global, per-role, and instance memory resolution and precedence.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 63ac075

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

Adds VoltAgent-level default memory support: a shared memory plus optional agentMemory and workflowMemory. Defaults are stored in AgentRegistry and applied to agents and workflows during registration; explicit per-instance memory (including false) retains precedence.

Changes

Cohort / File(s)	Summary
Types & Changelog packages/core/src/types.ts, .changeset/every-waves-win.md	Add memory, agentMemory, workflowMemory to VoltAgentOptions; add changelog entry describing default memory semantics.
Registry Memory Globals packages/core/src/registries/agent-registry.ts	Add globalMemory, globalAgentMemory, globalWorkflowMemory fields and accessors (set/getGlobal*Memory) with fallback semantics.
VoltAgent orchestration packages/core/src/voltagent.ts	Store defaultAgentMemory/defaultWorkflowMemory from options; register them in registry; add applyDefaultMemoryToAgent / applyDefaultMemoryToWorkflow; apply defaults during agent/workflow registration.
Agent memory resolution packages/core/src/agent/agent.ts	Track memoryConfigured; resolve memory from explicit value or registry global; add __setDefaultMemory(memory) to apply defaults when memory not explicitly set; derive public state from resolved memory instance.
Workflow memory behavior packages/core/src/workflow/core.ts	Introduce defaultMemory/executionMemory chain; expose __setDefaultMemory on workflows to set defaults post-creation; route workflow memory operations through resolved memory.
MemoryManager API packages/core/src/memory/manager/memory-manager.ts	Add `setMemory(memory: Memory
Tests packages/core/src/*.spec.ts	Add tests covering global memory defaults for agents, workflows, and VoltAgent; include registry reset helpers (note: one agent test suite duplicated).
Docs & Site website/docs/agents/memory/overview.md, website/docs/workflows/overview.md, website/docs/getting-started/voltagent-instance.md, website/sidebars.ts	Document global defaults, fallback rules, usage examples, add VoltAgent instance guide, and update sidebar navigation.

Sequence Diagram(s)

sequenceDiagram
    participant App as Application
    participant VA as VoltAgent
    participant Reg as AgentRegistry
    participant Agent as Agent
    participant MM as MemoryManager

    App->>VA: new VoltAgent({ memory?, agentMemory?, workflowMemory? })
    VA->>Reg: setGlobalMemory(memory)
    VA->>Reg: setGlobalAgentMemory(agentMemory)
    VA->>Reg: setGlobalWorkflowMemory(workflowMemory)

    App->>VA: registerAgent(agent)
    VA->>VA: applyDefaultMemoryToAgent(agent)
    VA->>Agent: __setDefaultMemory(defaultAgentMemory)
    Agent->>Reg: getGlobalAgentMemory()
    Reg-->>Agent: globalAgentMemory or globalMemory or undefined
    Agent->>MM: new MemoryManager(resolvedMemory)

Loading

sequenceDiagram
    participant App as Application
    participant VA as VoltAgent
    participant Workflow as Workflow
    participant Reg as AgentRegistry

    App->>VA: registerWorkflow(workflow)
    VA->>VA: applyDefaultMemoryToWorkflow(workflow)
    VA->>Workflow: __setDefaultMemory(defaultWorkflowMemory)
    Workflow->>Reg: getGlobalWorkflowMemory()
    Reg-->>Workflow: globalWorkflowMemory or globalMemory or undefined
    Note over Workflow: executionMemory = workflow.memory || default chain

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I found defaults beneath VoltAgent’s crown,
Shared memory hills where workflows settle down,
Agents sip from the registry stream,
Explicit beats default, as bright as a beam,
Hopping on — memories linked, cozy and sound.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title 'feat: add voltagent-level memory' directly and concisely describes the main feature being added—VoltAgent-level default memory configuration.
Description check	✅ Passed	The PR description is comprehensive, covering current behavior, new behavior, test/doc updates, and includes an auto-generated summary by cubic explaining the feature, implementation, and precedence rules.

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

✨ Finishing touches

• 📝 Generate docstrings

---

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

[cubic-dev-ai]

No issues found across 11 files

[cloudflare-workers-and-pages]

Deploying voltagent with    Cloudflare Pages

Latest commit:	63ac075
Status:	✅  Deploy successful!
Preview URL:	https://d353bf6f.voltagent.pages.dev
Branch Preview URL:	https://feat-add-default-memory.voltagent.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/core/src/agent/agent.spec.ts`:
- Around line 1182-1188: Add a beforeEach to the "Global Memory Defaults" suite
that mirrors the existing afterEach reset so the suite is order-independent:
call AgentRegistry.getInstance() and invoke setGlobalAgentMemory(undefined),
setGlobalWorkflowMemory(undefined), and setGlobalMemory(undefined) in beforeEach
(matching the afterEach) to ensure any prior tests' global defaults are cleared
before each test runs.