Memory Operations

Share data across agents with hierarchical, scoped memory

Memory Operations

Share data across agents with hierarchical, scoped memory

Agentfield's memory system enables agents to share data across distributed systems with automatic scope resolution. Memory is hierarchical—workflow → session → actor → global—allowing agents to access the right context without manual key management.

Quick Start

Store and retrieve memory across agents:

# Set memory (actor-scoped)
curl -X POST http://localhost:8080/api/v1/memory/set \
  -H "Content-Type: application/json" \
  -H "X-Actor-ID: user_john_doe" \
  -d '{
    "key": "user_preferences",
    "data": {
      "communication_style": "concise",
      "timezone": "America/New_York"
    }
  }'

# Get memory (hierarchical search)
curl -X POST http://localhost:8080/api/v1/memory/get \
  -H "Content-Type: application/json" \
  -H "X-Actor-ID: user_john_doe" \
  -d '{"key": "user_preferences"}'

Memory Scopes

Memory is automatically scoped based on HTTP headers:

ScopeHeaderUse CaseExample
WorkflowX-Workflow-IDData shared within a single workflow executionIntermediate results, workflow state
SessionX-Session-IDUser session data across multiple workflowsConversation history, session preferences
ActorX-Actor-IDUser/agent-specific dataUser preferences, learned behaviors
Global(none)System-wide configurationFeature flags, global settings

Hierarchical Resolution

When retrieving memory without an explicit scope, Agentfield searches hierarchically:

  1. Workflow scope (if X-Workflow-ID header present)
  2. Session scope (if X-Session-ID header present)
  3. Actor scope (if X-Actor-ID header present)
  4. Global scope (always checked last)

This allows agents to access the most specific context first, falling back to broader scopes automatically.

Set Memory

Note: The current control plane expects a JSON payload sent via POST for deletion. DELETE requests are not registered by the server yet.

Examples

# Actor-scoped memorycurl -X POST http://localhost:8080/api/v1/memory/set \-H "Content-Type: application/json" \-H "X-Actor-ID: user_john_doe" \-d '{  "key": "user_preferences",  "data": {    "communication_style": "concise",    "timezone": "America/New_York"  }}'# Session-scoped memorycurl -X POST http://localhost:8080/api/v1/memory/set \-H "Content-Type: application/json" \-H "X-Session-ID: session_123" \-d '{  "key": "conversation_context",  "data": {    "topic": "product support",    "messages_count": 5  }}'

Get Memory

Examples

# Hierarchical search (checks all scopes)curl -X POST http://localhost:8080/api/v1/memory/get \-H "Content-Type: application/json" \-H "X-Actor-ID: user_john_doe" \-d '{"key": "user_preferences"}'# Explicit scopecurl -X POST http://localhost:8080/api/v1/memory/get \-H "Content-Type: application/json" \-H "X-Actor-ID: user_john_doe" \-d '{  "key": "user_preferences",  "scope": "actor"}'

Delete Memory

Examples

curl -X POST http://localhost:8080/api/v1/memory/delete \-H "Content-Type: application/json" \-H "X-Actor-ID: user_john_doe" \-d '{"key": "user_preferences"}'

List Memory

Examples

curl "http://localhost:8080/api/v1/memory/list?scope=actor" \-H "X-Actor-ID: user_john_doe"

Cross-Agent Memory Patterns

Pattern 1: Learning User Preferences

Agent A learns and stores preferences, Agent B adapts automatically:

# Agent A: Customer support learns preference
import requests

requests.post(
    'http://localhost:8080/api/v1/memory/set',
    headers={'X-Actor-ID': 'user_123'},
    json={
        'key': 'communication_style',
        'data': 'concise'
    }
)

# Agent B: Marketing agent (different server) adapts
response = requests.post(
    'http://localhost:8080/api/v1/memory/get',
    headers={'X-Actor-ID': 'user_123'},
    json={'key': 'communication_style'}
)

style = response.json()['data']  # Returns 'concise'
# AI adjusts response based on learned preference

Pattern 2: Workflow State Management

Share intermediate results across workflow steps:

// Step 1: Store analysis results
await fetch('http://localhost:8080/api/v1/memory/set', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Workflow-ID': 'wf_analysis_001'
  },
  body: JSON.stringify({
    key: 'sentiment_analysis',
    data: {
      sentiment: 'positive',
      confidence: 0.94,
      topics: ['product', 'pricing']
    }
  })
});

// Step 2: Retrieve in next agent
const response = await fetch('http://localhost:8080/api/v1/memory/get', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Workflow-ID': 'wf_analysis_001'
  },
  body: JSON.stringify({ key: 'sentiment_analysis' })
});

const analysis = await response.json();
// Use analysis.data in next step

Pattern 3: Session Context

Maintain conversation context across multiple interactions:

# First interaction
curl -X POST http://localhost:8080/api/v1/memory/set \
  -H "X-Session-ID: session_456" \
  -d '{
    "key": "conversation_topic",
    "data": "product_support"
  }'

# Later interaction (same session)
curl -X POST http://localhost:8080/api/v1/memory/get \
  -H "X-Session-ID: session_456" \
  -d '{"key": "conversation_topic"}'
# Returns: "product_support"

Memory Events

Subscribe to memory changes in real-time using WebSocket or Server-Sent Events:

// WebSocket subscription
const ws = new WebSocket('ws://localhost:8080/api/v1/memory/events/ws');

ws.onmessage = (event) => {
  const change = JSON.parse(event.data);
  console.log('Memory changed:', change);
  // {
  //   type: 'memory_change',
  //   scope: 'actor',
  //   scope_id: 'user_123',
  //   key: 'preferences',
  //   action: 'set',
  //   data: {...}
  // }
};

// Server-Sent Events
const eventSource = new EventSource('http://localhost:8080/api/v1/memory/events/sse');

eventSource.onmessage = (event) => {
  const change = JSON.parse(event.data);
  console.log('Memory changed:', change);
};

Best Practices

1. Choose the Right Scope

Use the most specific scope for your use case:

  • Workflow: Temporary data for a single workflow execution
  • Session: User session data that persists across workflows
  • Actor: Long-term user/agent preferences and learned behaviors
  • Global: System-wide configuration (use sparingly)

2. Use Descriptive Keys

Choose clear, namespaced keys:

# Good
'user_preferences.communication_style'
'workflow_state.current_step'
'session_context.conversation_topic'

# Avoid
'data'
'temp'
'x'

3. Handle Missing Keys

Always handle cases where memory doesn't exist:

response = requests.post(
    'http://localhost:8080/api/v1/memory/get',
    headers={'X-Actor-ID': 'user_123'},
    json={'key': 'preferences'}
)

if response.status_code == 404:
    # Use defaults
    preferences = {'style': 'detailed'}
else:
    preferences = response.json()['data']

4. Clean Up Workflow Memory

Delete workflow-scoped memory after completion to avoid storage bloat:

curl -X POST http://localhost:8080/api/v1/memory/delete \
  -H "X-Workflow-ID: wf_completed_001" \
  -d '{"key": "intermediate_results"}'
PreviousAgent Discovery
NextWorkflow Management