Agent Memory

Agent memory lets agents persist state across runs so they can continue work instead of starting from scratch each time.

When Agent Memory Is Critical

Agent memory is particularly critical in several scenarios:

Long-running agents with multi-step executions.
Flows where each step needs to save data for the next step.
Cases where generated data is too large to keep only in runtime memory and must be persisted.
Advanced orchestration patterns where one agent must pass a large amount of information to another agent.

Agent Configuration vs Agent Memory

Do not confuse these two concepts:

	Agent configuration	Agent memory
Purpose	How an agent is set up to run	Data the agent reads and writes while operating
Examples	Model choice, crawl depth, knowledge sources, persona settings	Discovered leads, draft emails, report payloads, shared vendor fingerprints
Scope	Per tenant agent instance (configuration on the instance)	Varies by memory scope (see below)

Configuration tells an agent how to behave. Memory holds what the agent has learned, produced, or needs for the next step.

How Agent Memory Works

Each memory row stores a JSON payload (

memory_json

) under a

memory_key

. A

memory_type

label (for example

working

domain

organization

) helps group related rows but does not define the payload shape — the JSON can hold anything the agent needs.

By default, agent memory is recorded per squad, per tenant agent instance, and per run.

Depending on the orchestration need, memory can also be limited to:

Per squad and per tenant agent instance (
```
SQUAD_AGENT
```
).
Per tenant agent instance and per run (
```
AGENT_RUN
```
).
Per squad and per run (
```
SQUAD_RUN
```
).
Per squad only (
```
SQUAD
```
) — shared blackboard across agents in the squad.
Per parent agent (
```
AGENT
```
) — shared across all squads and all instances of that agent type.

With different scope limits, agent memory can behave like a common repository, a whiteboard for collaboration, a run-specific handoff buffer, or agent-wide shared data.

Agent Memory

Scope Levels

Scope	Shared across	Typical use
`SQUAD_AGENT_RUN`	One run, one tenant agent instance, one squad	Step-by-step handoff inside a single execution
`SQUAD_AGENT`	One tenant agent instance, one squad (any run)	Durable pipeline state (keywords, domains, drafts)
`AGENT_RUN`	One run, one tenant agent instance (any squad)	Run-scoped state tied to the instance, not the squad
`SQUAD_RUN`	One run, one squad (any tenant agent instance)	Squad-wide run context
`SQUAD`	One squad (any tenant agent instance, any run)	Squad blackboard / shared coordination
`AGENT`	All squads and all instances of the parent agent	Agent-wide shared data

Squad-scoped rows are keyed by

tenant_agent_id

squad_id

run_id

when applicable). AGENT-scoped rows are keyed by the parent

Agent.id

and are not tied to a squad or tenant agent instance.

AGENT-Scoped Memory

AGENT

scope is for data that belongs to the agent type itself, not to a particular squad deployment or instance.

Characteristics:

```
agent_id
```
points to the parent agent definition (for example the AI Opportunity Analyst agent type).
```
tenant_agent_id
```
,
```
squad_id
```
, and
```
run_id
```
are null.
```
memory_key
```
identifies the data set (for example
```
live_chat_vendors
```
).
```
memory_json
```
holds arbitrary structured data — there is no fixed schema across agents.
Rows are not listed in squad memory APIs; they are loaded explicitly by agents that need them.

Platform Defaults and Tenant Overrides

For

AGENT

scope, PrimePilot supports a read pattern where:

Platform data lives under the system tenant and provides defaults for all customers.
Tenant data (optional) under the same
```
agent_id
```
+
```
memory_key
```
overrides or extends those defaults on read.

Agents merge platform and tenant payloads when loading. The merge rules depend on the data shape — each agent defines how its own keys combine.

Example: Live-Chat Vendor Fingerprints

The AI Opportunity Analyst loads

memory_key = live_chat_vendors

AGENT

scope to detect Intercom, Tidio, HubSpot, PrimePilot, and other widgets on prospect websites. The JSON holds vendor IDs, display labels, and HTML signal strings. Platform defaults are seeded once; tenants can add or override vendors without changing agent code.

See AI Opportunity Analyst for how this data is used in reports.

Squad-Scoped Memory in Workspaces

In workspaces such as Lead Generation, squad-scoped memory powers the pipeline UI — keywords, domains, organisations, contacts, outbound drafts, and generated reports appear as memory rows scoped to the active squad.

These rows use

SQUAD_AGENT

(or related squad scopes) and are visible through squad memory APIs. They are distinct from

AGENT

-scoped data, which is shared infrastructure for the agent type rather than per-squad pipeline state.

Agent Memory

When Agent Memory Is Critical

Agent Configuration vs Agent Memory

How Agent Memory Works

Scope Levels

AGENT-Scoped Memory

Platform Defaults and Tenant Overrides

Example: Live-Chat Vendor Fingerprints

Squad-Scoped Memory in Workspaces

Related Documentation