Agent State & Memory

How agents maintain context, remember conversations, and adapt their behavior.

Overview

Unlike stateless API calls, Hyperfold agents maintain rich context throughout negotiations. They remember what products were discussed, what offers were made, and what the buyer's preferences are—enabling multi-turn conversations that feel natural.

Agent state is stored in Firestore for low-latency access during negotiations. Session data is automatically cleaned up after expiration.

State Types

Agents work with three types of state:

Configuration State

Static settings that define how the agent behaves: system prompts, pricing policies, tool permissions. Changed via hyperfold agent prompt commands.

Session State

Dynamic context for an active negotiation: buyer info, conversation history, cart contents, pricing context. Created when a session starts, deleted on expiry.

Long-Term Memory

Persistent learnings that improve over time: successful negotiation tactics, customer preference patterns, product performance insights.

Session Context

Each negotiation session maintains a context object that the agent references for every decision:

json

{
  "session_id": "sess_abc123",
  "created_at": "2025-12-19T10:30:00Z",
  "expires_at": "2025-12-19T11:30:00Z",
 
  "buyer": {
    "agent_id": "openai_gpt4_buyer",
    "user_id": "user_xyz",
    "loyalty_tier": "gold",
    "purchase_history": {
      "total_orders": 12,
      "total_spent": 2450.00,
      "avg_order_value": 204.17,
      "favorite_categories": ["footwear", "sportswear"]
    }
  },
 
  "conversation": {
    "turn_count": 4,
    "products_discussed": ["prod_aero_x2", "prod_storm_gt"],
    "offers_made": [
      {"price": 120, "status": "rejected"},
      {"price": 140, "status": "countered", "counter": 155}
    ],
    "current_cart": {
      "items": [{"product_id": "prod_aero_x2", "quantity": 1}],
      "subtotal": 155.00
    }
  },
 
  "pricing_context": {
    "floor_price": 92.00,
    "competitor_price": 165.00,
    "inventory_status": "normal",
    "max_discount_remaining": 0.20
  }
}

Context Variables

Variable	Source	Updated
`buyer.loyalty_tier`	CRM integration	Session start
`pricing_context.floor_price`	Pricing policy + product cost	Each turn
`pricing_context.competitor_price`	Redis cache	15-min refresh
`conversation.offers_made`	Session history	Each turn
`inventory_status`	Cloud Spanner	Real-time

Memory Scopes

Agent memory is organized hierarchically in Firestore:

text

# Firestore Memory Structure
 
/agents/{agent_id}/
  ├── config/
  │   ├── system_prompt        # Base instructions
  │   ├── pricing_policy       # Margin rules
  │   └── tool_permissions     # Allowed actions
  │
  ├── sessions/{session_id}/
  │   ├── context              # Buyer info, cart state
  │   ├── conversation         # Turn history
  │   └── decisions            # Reasoning log
  │
  └── memory/
      ├── long_term/           # Persistent learnings
      │   ├── successful_tactics
      │   ├── customer_preferences
      │   └── product_insights
      │
      └── working/             # Ephemeral scratch space
          └── current_reasoning

Working Memory

During a negotiation, the agent maintains working memory for its "chain of thought"— the reasoning process it uses to make decisions. This is ephemeral and cleared after each session.

Long-Term Learning

Optionally, agents can persist learnings that improve future negotiations:

Successful tactics: What discount strategies led to conversions
Customer preferences: Brand affinities, price sensitivity patterns
Product insights: Which products pair well, common objections

Long-term memory requires explicit opt-in due to privacy considerations. Customer data is anonymized before storage.

Hot-Swapping Prompts

One of Hyperfold's most powerful features is the ability to change agent behavior instantly, without redeploying code:

bash

# Hot-swap agent personality/strategy without redeployment
 
# View current prompt
$ hyperfold agent prompt get --agent="sales-bot-01"
 
> Current System Prompt:
> You are a friendly sales agent for Acme Sports.
> Be helpful but protect margins. Never go below floor price.
 
# Switch to aggressive sales mode
$ cat > prompts/aggressive.txt << 'EOF'
You are a results-driven sales agent for Acme Sports.
Your goal is to close every deal. Be persuasive.
Emphasize value, scarcity, and time-limited offers.
Use urgency tactics when inventory is high.
Never go below floor price.
EOF
 
$ hyperfold agent prompt set --agent="sales-bot-01" --file="./prompts/aggressive.txt"
 
> [Hyperfold] Validating safety guardrails... OK
> [Firestore] System Instruction updated
> [Live Status] Agent behavior updated instantly. No redeploy required.
 
# The next negotiation uses the new personality immediately

Context Injection

For temporary situations (outages, flash sales, weather events), inject context without modifying the base prompt:

bash

# Inject temporary context without changing base prompt
$ hyperfold agent prompt patch \
  --agent="sales-bot-01" \
  --append="CRITICAL: Warehouse Ohio is down. No 2-day shipping for zip codes 43xxx-45xxx."
 
> [Firestore] Context appended to active session
> [Live Status] All new negotiations will include this context
 
# Remove the temporary context
$ hyperfold agent prompt patch \
  --agent="sales-bot-01" \
  --remove="CRITICAL: Warehouse Ohio*"
 
> [Firestore] Context removed
> [Live Status] Normal operations resumed

See real-time agent reasoning with the agent logs command.