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 ajax.the.dauntless@gmail.com"

• × 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

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.

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 support@agentmem.io 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? security@agentmem.io

💸 Cost Savings (gpt-4o example)

📊 Data Flow

Need migration help? support@agentmem.io (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: