Persistent Memory

Store and recall facts, preferences, and insights across workflow executions. The primitive that powers Business Memory and User Context — and available directly to any workflow step or MCP client.

What is Persistent Memory?

By default, data in a workflow exists only for that run. Persistent Memory breaks that constraint. Any step can write a named value into the memory store, and any future step — in the same workflow or a completely different one — can read it back by key.

This is how a scoring workflow accumulates calibration data over dozens of runs, how an outreach agent remembers which tone a user prefers, and how a proactive agent tracks whether a threshold was crossed yesterday.

Scopes

Every memory entry belongs to exactly one scope. The scope determines who can read it and how long it lives relative to a workflow.

workspace

Shared across all workflows and all users in the workspace. This is what Business Memory is built on. Use it for ICP definitions, scoring rubrics, brand voice, and anything that should be consistent workspace-wide. Capacity: 1,000 entries.

workflow

Scoped to a single workflow. Entries survive across executions of the same workflow but are not visible to other workflows. Use it for per-workflow counters, calibration data, and run-over-run learning. Capacity: 500 entries.

user

Scoped to the calling user within the workspace. This is what User Context is built on. Use it for preferences, owned accounts, and personal interaction history. One user's entries are invisible to other users.

MCP Tools

Five MCP tools cover the full memory lifecycle. All scope to workspace by default; pass scope to override.

store_memory

store_memory({
  key: "icp_definition",
  value: { industry: ["SaaS"], headcount: "11-200" },
  category: "fact",         // fact | insight | preference | outcome
  scope: "workspace",
  confidence: 90,           // 0–100; ≥70 auto-syncs to Knowledge Graph
  merge: "overwrite"        // overwrite | append | max | min | increment
})

recall_memory

recall_memory({
  key: "icp_definition",
  scope: "workspace"
})

search_memories

search_memories({
  query: "scoring rules for enterprise deals",
  scope: "workspace",
  category: "fact",
  limit: 20          // default 20
})

list_memories

list_memories({
  scope: "workflow",
  workflowId: "wf_investor_scoring",
  category: "outcome",
  limit: 50          // default 50
})

delete_memory

delete_memory({
  key: "icp_definition",
  scope: "workspace"
})

Merge Strategies

When a key already exists, the merge strategy controls what happens instead of a blind overwrite.

Strategy	Behavior
overwrite	Replace the existing value entirely. Default.
append	Push new items into an array, growing a collection over time.
increment	Add numeric values — useful for counters and running totals.
max	Keep the larger numeric value. Useful for high-water marks.
min	Keep the smaller numeric value.

TTL & Expiry

Pass ttl (seconds) to make a memory expire automatically. Omit it or pass null for a permanent entry.

store_memory({
  key: "weekly_market_signal",
  value: "fintech M&A activity elevated",
  category: "insight",
  scope: "workspace",
  ttl: 604800   // 7 days in seconds
})

Persistent Memory vs. Passing Data Between Steps

Use stepswhen data only needs to flow within a single execution. Step output references ({{steps.stepId.output}}) are the right tool — no memory write/read overhead.

Use memorywhen data needs to survive across executions, be shared with other workflows, or accumulate over time (counters, calibration data, learned preferences).

Knowledge Graph Sync

Entries with confidence ≥ 70 are asynchronously promoted to insight nodes in the Knowledge Graph. This makes them searchable via kg_search alongside entities and relationships. Sync is fire-and-forget — DynamoDB is the source of truth and nothing blocks on KG availability.

Capacity & Eviction

•workspace scope: 1,000 entries maximum
•workflow scope: 500 entries per workflow
•When the cap is hit, the lowest-confidence entries are evicted first to make room for new writes.

Next Steps

Business Memory — Workspace-scoped memory for shared company knowledge
User Context — User-scoped memory for personal preferences and history
Proactive Agents — Agents that monitor memory conditions and act on them
KG API — Query memory entries promoted to Knowledge Graph insight nodes