You forget — AgentMem remembers. 🧠

• → 💚 User preferences
  e.g. "I prefer TypeScript over JavaScript"
• → 📌 Ongoing context
  e.g. "Currently launching AgentMem v1.0"
• → 🟤 Decisions made
  e.g. "Use Cloudflare Pages for hosting"
• → 📌 Entity tracking
  e.g. Names, accounts, project IDs, API tokens
• → 🚨 Facts worth remembering
  e.g. "Email is [email protected]"

• × Temporary state
  e.g. "API request loading..." (session-only)
• × Secrets & credentials
  Use environment variables instead
• × Large blobs
  Images, videos → use object storage (S3/R2)
• × High-frequency counters
  e.g. Real-time analytics → use Redis/ClickHouse
• × Full conversation logs
  Use vector search for RAG instead

• → Store decisions explicitly
  Don't assume memory sticks — write it
• → Use consistent key structure
  e.g. user:123:preference:timezone
• → Check memory before asking
  Search first, then ask user if not found
• → Store facts, not speculation
  Only write confirmed information

• × Copy chat transcripts
  Store context, not raw messages
• × Store secrets/passwords
  Use environment variables instead
• × Overwrite without checking
  GET first, then update if needed
• × Store temporary state
  Loading indicators belong in session

Atomic Writes

Every PUT is atomic. Either the write succeeds completely, or it fails. No partial updates, no corruption.

R2 Consistency

Cloudflare R2 eventual consistency guarantees your data persists across multiple datacenters. Strong read-after-write consistency.

99.9% Uptime

Backed by Cloudflare's global network. No single point of failure. Automatic failover across regions.

📈 Trading Bot

Track portfolio state, risk limits, and recent trades across sessions.

# Store risk limit
curl -X PUT https://api.agentmem.io/v1/keys/risk_limit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "max_position_5_percent"

# Log trade
curl -X PUT https://api.agentmem.io/v1/keys/trades/$(date +%s) \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "BUY 100 AAPL @ 150.25"

# Retrieve risk limit before trading
RISK=$(curl -s https://api.agentmem.io/v1/keys/risk_limit \
  -H "Authorization: Bearer YOUR_API_KEY")

💬 Support Agent

Remember customer preferences, issue history, and resolution notes.

# Store customer preference
curl -X PUT https://api.agentmem.io/v1/keys/customer/alice/preferences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "prefers_email_over_phone"

# Log issue resolution
curl -X PUT https://api.agentmem.io/v1/keys/tickets/12345/resolution \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "Reset password + enabled 2FA"

# Bulk retrieve customer context
curl https://api.agentmem.io/v1/keys?prefix=customer/alice/ \
  -H "Authorization: Bearer YOUR_API_KEY"

⚙️ DevOps Agent

Track deployment state, config hashes, and incident notes.

# Store deployment hash
curl -X PUT https://api.agentmem.io/v1/keys/prod/deploy_hash \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "abc123def456"

# Log incident
curl -X PUT https://api.agentmem.io/v1/keys/incidents/$(date +%Y-%m-%d-%H%M) \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "CPU spike 90% resolved by scaling workers"

# Check last deploy before rollback
HASH=$(curl -s https://api.agentmem.io/v1/keys/prod/deploy_hash \
  -H "Authorization: Bearer YOUR_API_KEY")

🤖 Personal Assistant

Remember user preferences, habits, and important dates.

# Store preference
curl -X PUT https://api.agentmem.io/v1/keys/preferences/communication \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "direct_no_fluff"

# Store important date
curl -X PUT https://api.agentmem.io/v1/keys/dates/anniversary \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "2024-06-15"

# Retrieve all preferences on session start
curl https://api.agentmem.io/v1/keys?prefix=preferences/ \
  -H "Authorization: Bearer YOUR_API_KEY"

🟢 On Session Start

1. Load user preferences: GET /v1/keys?prefix=preferences/
2. Check for pending tasks: GET /v1/keys?prefix=tasks/pending/
3. Retrieve recent context: GET /v1/keys/session/last_state

💬 During Conversation

🔴 On Session End

1. Save final state: PUT session/last_state
2. Mark completed tasks: DELETE tasks/pending/{id}
3. Archive important decisions to long-term: PUT archive/{date}

❌ Flat key namespace

user_pref_1
user_pref_2
task_1
task_2

Problem: Can't bulk retrieve related keys.

✅ Hierarchical prefixes

preferences/communication
preferences/ui_theme
tasks/pending/deploy
tasks/completed/bugfix

Benefit: GET /v1/keys?prefix=preferences/ returns all preferences.

❌ Storing large blobs

PUT /v1/keys/full_transcript
Value: [10,000 lines of chat history]

Problem: High latency, expensive storage.

✅ Store distilled summaries

PUT /v1/keys/session_summary
Value: "Discussed API design, decided on REST, implemented /users endpoint"

Benefit: Fast retrieval, low cost, easier to search.

❌ No cleanup strategy

Problem: Keys accumulate forever, bloating namespace and costs.

✅ Regular pruning

# Weekly cleanup of old tasks
curl https://api.agentmem.io/v1/keys?prefix=tasks/completed/ \
  -H "Authorization: Bearer YOUR_API_KEY" | \
  jq -r '.keys[] | select(.lastModified < '$(date -d '30 days ago' +%s)') | .key' | \
  xargs -I {} curl -X DELETE https://api.agentmem.io/v1/keys/{} \
    -H "Authorization: Bearer YOUR_API_KEY"

Benefit: Keep memory lean, reduce costs, faster scans.

Before & After

The simplicity moat: We're the ONLY memory solution that's
zero-dependency, one-line setup, and crypto-native.

🎯 The Rule: If it must survive compaction, store it in AgentMem

Session memory is ephemeral. Daily logs are operational. AgentMem is your source of truth.

Example workflow:

• User says "I prefer dark mode" → Store in AgentMem (PUT /kv/user_prefs)
• Working on a bug → Log in daily/2026-02-05.md
• Bug fixed, decision made → Update AgentMem (PUT /kv/decisions/2026-02-05-01)

💡 Inspired by: OpenClaw-Mem's three-layer architecture (ephemeral → operational → durable)

🚀 Why It's Fast

• ✅ Cloud-native infrastructure: Cloudflare Workers + Durable Objects (edge computing)
• ✅ Zero cold starts: Always-on Durable Objects maintain state
• ✅ Simple API: No complex queries = predictable latency

📊 Uptime & Monitoring

• 🟢 Health endpoint: GET /v1/health for service status
• 📈 Analytics API: GET /v1/analytics for usage metrics
• 🔍 Full audit trail: Every operation logged with timestamp

🎯 Token Cost Impact

AgentMem adds minimal overhead to your token budget. Here's the math:

💡 Pro tip: Use short keys and store only essential data to minimize token usage

⚠️ What Happens When You Hit Limits?

• 🚦 Rate limit: 429 response with Retry-After header
• 📦 Value too large: 413 Payload Too Large (compress or use S3)
• 🔑 Key too long: 400 Bad Request with hint to shorten

Get all your agent's context in a single API call. Perfect for session startup.

curl https://api.agentmem.io/v1/bootstrap \
  -H "Authorization: Bearer YOUR_API_KEY"

# Returns: identity + all memories + stats in ONE call

Why: Initialize with essential context so the agent doesn't ask for preferences every time.

Why: Store facts in real-time so they're available in future sessions.

Why: Capture decisions and learnings for future reference ("Why did we pick this?").

Why: Don't repeat mistakes. Learn from failures.

Why: Consolidate ephemeral chat into durable memories.

📋 Copy-Paste for AGENTS.md / HEARTBEAT.md

## Memory Protocol (AgentMem)

On session start:
1. GET /v1/bootstrap (identity + core context)
2. GET /v1/keys?prefix=critical: (never-forget rules)
3. GET /v1/keys?prefix=user:pref: (user preferences)

During conversation:
- User says "remember this" → PUT immediately
- User says "I prefer X" → PUT as user:pref:{topic}
- User asks "what did I..." → GET episodic:*

On session end:
1. Extract durable facts → PUT semantic:{topic}
2. Record lessons learned → PUT lesson:{topic}
3. Consolidate decisions → PUT decision:{topic}

📦 Install Helper Script

Download and install the amem helper script for easier CLI usage:

💡 Set your API key: export AGENTMEM_API_KEY="your-key"

🚀 Usage Examples

#!/bin/bash
# AgentMem Helper Script
# Usage: amem [set|get|search|delete|bootstrap] [args...]

API_KEY="${AGENTMEM_API_KEY:-}"
BASE_URL="https://api.agentmem.io/v1"

if [ -z "$API_KEY" ]; then
  echo "Error: AGENTMEM_API_KEY not set"
  exit 1
fi

case "$1" in
  set)
    curl -X PUT "$BASE_URL/$2" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: text/plain" \
      -d "$3"
    ;;
  get)
    curl -X GET "$BASE_URL/$2" \
      -H "Authorization: Bearer $API_KEY"
    ;;
  search)
    curl -X GET "$BASE_URL/keys?prefix=$2" \
      -H "Authorization: Bearer $API_KEY"
    ;;
  delete)
    curl -X DELETE "$BASE_URL/$2" \
      -H "Authorization: Bearer $API_KEY"
    ;;
  bootstrap)
    curl -X GET "$BASE_URL/bootstrap" \
      -H "Authorization: Bearer $API_KEY"
    ;;
  *)
    echo "Usage: amem [set|get|search|delete|bootstrap] [args...]"
    exit 1
    ;;
esac

Core Principle: Precision over Quantity

Don't dump all memories into context. Retrieve selectively — load only what's needed for the current task. Fewer tokens = faster responses + lower costs.

Why: List all keys in a namespace first. Pick the 1-3 most relevant keys before fetching values.

Why: Most tasks only need 1-3 memories. Load the minimum required data.

Why: Reduce API calls. Load critical context once at session start, reuse throughout.

Why: If you don't know what to retrieve, ask the user instead of scanning everything.

Why: Dead keys clutter your namespace. Periodically delete stale data (old sessions, expired cache, etc.).

⚡ Quick Reference

For easier usage, create ~/bin/agentmem:

#!/bin/bash
# AgentMem CLI Helper
KEY="${AGENTMEM_KEY:?Set AGENTMEM_KEY env var}"
ACTION=$1
KEYNAME=$2
shift 2

case $ACTION in
  put)
    echo "$*" | curl -X PUT "https://api.agentmem.io/v1/kv/$KEYNAME" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/text" \
      --data-binary @-
    ;;
  get)
    curl -s "https://api.agentmem.io/v1/kv/$KEYNAME" \
      -H "Authorization: Bearer $KEY"
    ;;
  delete)
    curl -X DELETE "https://api.agentmem.io/v1/kv/$KEYNAME" \
      -H "Authorization: Bearer $KEY"
    ;;
  *)
    echo "Usage: agentmem [put|get|delete] <key> [value]"
    exit 1
    ;;
esac

Silent operation: When users say these phrases, store immediately and continue — don't announce "I'll remember that!" Just do it.

📋 Python Implementation Example

import re
import requests

TRIGGER_PATTERNS = {
    'preference': r'I (prefer|like|want|hate)',
    'identity': r'My (name|timezone|email) is',
    'explicit': r'(remember|don\'t forget|note that)',
    'decision': r'(we decided|I chose|let\'s go with)',
    'lesson': r'(worked better|next time|what failed)',
    'delete': r'(forget that|delete|remove|clear)'
}

def detect_trigger(user_message):
    for category, pattern in TRIGGER_PATTERNS.items():
        if re.search(pattern, user_message, re.IGNORECASE):
            return category
    return None

def auto_capture(user_message, api_key):
    trigger = detect_trigger(user_message)
    if not trigger:
        return  # No trigger, skip
    
    # Extract key/value (simplified - use NER in production)
    key = f"{trigger}:{int(time.time())}"
    value = {"text": user_message, "category": trigger}
    
    # Store silently
    requests.put(
        f"https://api.agentmem.io/v1/{key}",
        headers={"Authorization": f"Bearer {api_key}"},
        json=value
    )

✅ Best Practices for Auto-Capture

Personal Assistant Memory

Remember user preferences, past decisions, and ongoing tasks. Your agent gets smarter over time, not goldfish-brained every conversation.

Multi-Agent Knowledge Sharing

Share context across specialized agents. One agent learns, all agents benefit. Perfect for agent swarms and delegation workflows.

Customer Context Persistence

Customer support agents that remember prior tickets, preferences, and history. No more "let me look that up" — instant context retrieval.

Agentic Workflow State

Pause and resume complex workflows. Your agent can checkpoint progress, survive restarts, and pick up where it left off.

Use AgentMem for: Structured key-value data (preferences, config, session state)
Use MEMORY.md for: Long-form notes, journal entries, human-readable logs

Use AgentMem for: Simple facts, configuration, exact-match lookups
Use Vector DBs for: Semantic search, similarity matching, large corpora

Use AgentMem for: Live data that changes frequently (session state, prefs)
Use Git for: Versioned history, audit trails, collaborative editing

Use AgentMem for: Persistent storage that survives restarts
Use Redis for: High-speed cache, pub/sub, ephemeral data (<1 hour)

Rule of Thumb:

If it needs to survive restarts → AgentMem
If it's <1 hour lifespan → Session memory

🚧 What AgentMem v1.0 Doesn't Do

• ❌ No semantic search: You can GET by key prefix, but no vector embeddings or similarity search (yet). Use client-side filtering for now.
• ❌ No built-in search API: GET /v1/keys returns all keys, then you filter client-side. Fast enough for <10k keys.
• ❌ No relational queries: It's key-value only. No JOINs, no complex queries. Simple by design.
• ❌ No automatic backups: Use GET /v1/export to download your data manually (GDPR-compliant).
• ❌ No multi-user collaboration: One API key = one namespace. Share keys carefully.

🚀 Coming Soon (Based on Demand)

• ❌ Don't store transient API errors
  Bad: {"error": "503 Service Unavailable"}
  Why: Errors are temporary. If you need to track failures, store patterns, not raw errors.
• ❌ Don't store massive payloads (>1MB)
  Bad: Storing entire API responses, large JSON blobs, base64-encoded images
  Why: AgentMem is for memory, not file storage. Use S3/R2 for large data, store references in AgentMem.
• ❌ Don't use AgentMem as a database
  Bad: Relational data with JOINs, complex queries, transactional data
  Why: AgentMem is key-value only. For structured data, use Postgres/MySQL. Store summaries in AgentMem.
• ❌ Don't store secrets in plain text
  Bad: {"github_token": "ghp_abc123..."}
  Why: Use environment variables or proper secret managers. AgentMem is for context, not credentials.

AgentMem is key-value only — no built-in tagging. But you can use key prefixes and JSON metadata to create your own tagging system.

# Organize by type
user:preferences:language
user:preferences:timezone
project:agentmem:api_key
project:agentmem:last_deploy

# Query by prefix
GET /v1/keys?prefix=user:preferences:
→ Returns all user preferences

GET /v1/keys?prefix=project:
→ Returns all project-related memories

{
  "key": "decision:2026-02-05:use-agentmem",
  "value": {
    "type": "decision",
    "priority": "high",
    "category": "architecture",
    "decision": "Use AgentMem for persistent memory",
    "reason": "Simple API, cloud-native, pay-as-you-go",
    "updated": "2026-02-05T03:58:00Z",
    "tags": ["memory", "architecture", "cloud"]
  }
}

# Fetch all memories
memories = api.get('/v1/keys?prefix=memory:')

# Filter by tag in JSON value
high_priority = [m for m in memories 
                 if m['value']['priority'] == 'high']

# Filter by date
recent = [m for m in memories 
          if m['value']['updated'] > '2026-02-01']

When to choose local: If you have strict data residency requirements, or need complete air-gap isolation, local-first solutions like elite-longterm-memory or openclaw-mem are better fits. AgentMem prioritizes speed + convenience + multi-device access over maximum control.

The Problem

Agents often fetch external content (web_search, web_fetch, API calls) during conversations. Not all of it is verified truth. Storing unverified data directly pollutes long-term memory.

The Solution: Pending Namespace

Use a pending: prefix for external content. Review before promoting to long-term memory.

✅ Verification Checklist (Before Promoting)

Four-Tier Importance System

📋 Retrieval Strategy by Importance

## Session Start Protocol (Prioritized Loading)

1. Load critical:* (always)
   GET /v1/keys?prefix=critical:
   → MUST load before any user interaction

2. Load high:* (very likely needed)
   GET /v1/keys?prefix=high:decision:
   GET /v1/keys?prefix=high:lesson:
   → Scan on startup or first user message

3. Load normal:* (on demand)
   IF user asks about topic:
     GET /v1/keys?prefix=normal:{topic}
   → Fetch only when contextually relevant

4. Skip low:* (unless explicitly requested)
   Only load if user specifically asks
   → Consider archiving after 30 days

🚀 Startup Checklist (Run Before Every Session)

🤖 Automated Health Check Script

Add this to your AGENTS.md or run it in heartbeat.

#!/bin/bash
# AgentMem Health Check

echo "🔍 Running pre-session health check..."

# 1. Bootstrap
bootstrap=$(curl -s -H "Authorization: Bearer $API_KEY" \
  https://api.agentmem.io/v1/bootstrap)
if [ -z "$bootstrap" ]; then
  echo "❌ Bootstrap failed"
  exit 1
fi

# 2. Critical rules
critical=$(curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.agentmem.io/v1/keys?prefix=critical:")
critical_count=$(echo "$critical" | jq '.keys | length')
if [ "$critical_count" -eq 0 ]; then
  echo "⚠️  No critical rules set"
fi

# 3. Pending memories
pending=$(curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.agentmem.io/v1/keys?prefix=pending:")
pending_count=$(echo "$pending" | jq '.keys | length')
if [ "$pending_count" -gt 10 ]; then
  echo "⚠️  $pending_count pending memories — review backlog"
fi

# 4. User preferences
prefs=$(curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.agentmem.io/v1/keys?prefix=user:pref:")
prefs_count=$(echo "$prefs" | jq '.keys | length')
echo "✅ $prefs_count user preferences loaded"

# 5. Low-priority cleanup
low=$(curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.agentmem.io/v1/keys?prefix=low:")
low_count=$(echo "$low" | jq '.keys | length')
if [ "$low_count" -gt 100 ]; then
  echo "⚠️  $low_count low-priority keys — consider archiving"
fi

echo "✅ Health check complete"

🗑️ When to Delete

✂️ How to Prune

curl -X DELETE "https://api.agentmem.io/v1/keys?prefix=temp_" \
  -H "Authorization: Bearer $KEY"

# Export all memories
curl -H "Authorization: Bearer $KEY" \
  https://api.agentmem.io/v1/export > backup.json

# Review backup.json, remove junk
# Reimport clean memories (write script to PUT each entry)

Still stuck? All API errors include "hint" and "docs" fields. Check the error response first — it usually tells you how to fix it.

Cause: Missing or incorrect API key.

Cause: Key doesn't exist, or you're GETting before PUTting.

Cause: Too many API calls in a short time window.

Cause: Single value exceeds 1MB limit.

Cause: Network issue or API temporarily unavailable.

Test your API connection and key validity:

Still having issues? Email [email protected] with your API key (last 4 chars) and error details. We respond within 24h.

Why We're Faster

What We Don't Do

• ❌ No training on your data — Your memories stay yours
• ❌ No third-party sharing — We don't sell, rent, or leak data
• ❌ No analytics tracking — We don't know what you store (encrypted)
• ❌ No vendor lock-in — Export anytime, host yourself if needed

Questions about security? [email protected]

💸 Cost Savings (gpt-4o example)

📊 Data Flow

Need migration help? [email protected] (we respond fast)

⏰ Periodic Memory Cleanup (OpenClaw Cron)

Set up a monthly cleanup job to prune old temporary keys and keep your namespace lean:

cron action=add job='{
  "name": "memory-cleanup",
  "schedule": { "kind": "cron", "expr": "0 4 1 * *" },
  "payload": {
    "kind": "agentTurn",
    "message": "Clean up AgentMem: 1) GET /v1/keys?prefix=temp: 2) DELETE keys older than 30d 3) Log completion"
  },
  "sessionTarget": "isolated"
}'

Runs monthly at 4 AM, removes stale temp:* keys, keeps your memory fresh.

💓 Heartbeat Integration (Proactive Context Loading)

Load critical memories during heartbeat polls to keep context fresh:

# In HEARTBEAT.md
## Memory Sync (every 30 min)
1. GET /v1/bootstrap (identity + core context)
2. If user:* keys updated_at > last_heartbeat:
   - Fetch new user:pref:* keys
   - Update local context
3. Log sync completion

Keeps your agent in sync with user preferences without explicit fetches.

Need a full integration guide? Open an issue on GitHub and we'll write it.

If you currently store memories in MEMORY.md or daily log files:

# 1. Extract key facts from MEMORY.md
grep "^- " MEMORY.md > facts.txt

# 2. Upload to AgentMem with structured keys
while read line; do
  key="semantic:$(echo $line | md5sum | cut -c1-8)"
  curl -X PUT "https://api.agentmem.io/v1/$key" \
    -H "Authorization: Bearer $API_KEY" \
    -d "$line"
done < facts.txt

# 3. Keep MEMORY.md as canonical source (for now)
# 4. Gradually shift to AgentMem as primary

If you use vector search (LanceDB, ChromaDB, Pinecone):

# Python migration script
import lancedb
import requests

db = lancedb.connect("~/.agent-memory/lance")
table = db.open_table("memories")

API_KEY = "your_api_key"
BASE = "https://api.agentmem.io/v1"

# Export all vectors to AgentMem
for row in table.to_pandas().itertuples():
    key = f"semantic:{row.topic}:{row.id}"
    requests.put(f"{BASE}/{key}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        data=row.text
    )

print("Migration complete! Test AgentMem, then archive LanceDB.")

If you use Git-backed memory stores (episodic, semantic, procedural):

# Sync episodic memories
for file in memory/episodes/*.md; do
  date=$(basename $file .md)
  curl -X PUT "https://api.agentmem.io/v1/episodic:$date" \
    -H "Authorization: Bearer $API_KEY" \
    --data-binary @$file
done

# Sync semantic graph
for entity in memory/graph/entities/*.md; do
  name=$(basename $entity .md)
  curl -X PUT "https://api.agentmem.io/v1/entity:$name" \
    -H "Authorization: Bearer $API_KEY" \
    --data-binary @$entity
done

# Sync procedural workflows
for workflow in memory/procedures/*.md; do
  name=$(basename $workflow .md)
  curl -X PUT "https://api.agentmem.io/v1/workflow:$name" \
    -H "Authorization: Bearer $API_KEY" \
    --data-binary @$workflow
done

You don't have to migrate everything. Use AgentMem for what it's best at: