---
name: agent-memory
version: 0.1.0
description: Encrypted vector memory for AI agent swarms. Store, search, and sync memories across instances.
homepage: https://memforge.xyz
metadata: {"category":"infrastructure","api_base":"https://memforge.xyz/api"}
---

# Agent Memory

Encrypted vector memory for AI agent swarms. Store memories, search semantically, sync across instances.

**Base URL:** `https://memforge.xyz`

## Register First

Every agent needs to register to get an API key:

```bash
curl -X POST https://memforge.xyz/register \
  -H "Content-Type: application/json" \
  -d '{"name": "YourAgentName", "description": "What you do"}'
```

Response:
```json
{
  "success": true,
  "agent": {
    "name": "YourAgentName",
    "api_key": "mk_xxxxxxxxxxxx",
    "tier": "free",
    "limits": {
      "storage_mb": 1,
      "queries_per_day": 100,
      "memories_max": 100
    }
  },
  "important": "⚠️ SAVE YOUR API KEY!"
}
```

**⚠️ Save your `api_key` immediately!** It cannot be recovered.

---

## Authentication

All requests after registration require your API key:

```bash
curl https://memforge.xyz/memory \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## Store a Memory

```bash
curl -X POST https://memforge.xyz/memory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "conversation-2024-01-30",
    "content": "Today I learned about x402 payments...",
    "metadata": {"type": "learning", "topic": "payments"}
  }'
```

**Fields:**
- `key` (required): Unique identifier for this memory
- `content` (required): The memory content (can be encrypted by you)
- `metadata` (optional): Searchable tags/attributes

---

## Retrieve a Memory

```bash
curl https://memforge.xyz/memory/conversation-2024-01-30 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## List All Memories

```bash
curl "https://memforge.xyz/memory?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## Update a Memory

```bash
curl -X PATCH https://memforge.xyz/memory/conversation-2024-01-30 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content...", "metadata": {"updated": true}}'
```

---

## Delete a Memory

```bash
curl -X DELETE https://memforge.xyz/memory/conversation-2024-01-30 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## Search Memories

Search by text query or metadata:

```bash
curl -X POST https://memforge.xyz/memory/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what did I learn about payments?",
    "metadata_filter": {"type": "learning"},
    "limit": 10
  }'
```

---

## Sync (For Swarms)

Get all memories changed since a version or timestamp:

```bash
curl -X POST https://memforge.xyz/memory/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since_version": 42}'
```

Response:
```json
{
  "success": true,
  "data": {
    "memories": [...],
    "latest_version": 57,
    "has_more": false
  }
}
```

**Use this for multi-instance setups:** Each agent polls for changes, applies them locally.

---

## Check Your Status

```bash
curl https://memforge.xyz/register/status \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Shows your tier, usage, and limits.

---

## Tiers

| Tier | Storage | Queries/Day | Memories | Price |
|------|---------|-------------|----------|-------|
| Free | 1 MB | 100 | 100 | $0 |
| Paid | Unlimited | Unlimited | Unlimited | Pay per use |

**Upgrade to paid:** Connect a wallet and pay via x402. Details at `/namespace/upgrade`.

---

## Tips for Swarm Usage

1. **Use the same API key** across all instances
2. **Poll `/memory/sync`** periodically to get updates from other instances
3. **Use unique keys** like `instance-1/conversation-123` to avoid conflicts
4. **Store metadata** for easy filtering (instance_id, type, timestamp)

---

## Encryption (Recommended)

We store whatever you send. For maximum privacy, **encrypt content client-side** before sending. Keep metadata unencrypted so search still works.

### How It Works

```
┌─────────────────────────────────────────────┐
│  Your Agent                                  │
├─────────────────────────────────────────────┤
│  content: "secret notes"  ──► encrypt ──►   │
│  metadata: {type: "note"} ──► as-is ────►   │
│                                              │
│         POST /memory                         │
│         {                                    │
│           content: "U2FsdGVk...",  ← encrypted│
│           metadata: {type: "note"} ← searchable│
│         }                                    │
└─────────────────────────────────────────────┘
```

### JavaScript (Node.js)

```javascript
import crypto from 'crypto';

const SECRET_KEY = process.env.MEMORY_ENCRYPTION_KEY; // 32 bytes hex

function encrypt(text) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', Buffer.from(SECRET_KEY, 'hex'), iv);
  let encrypted = cipher.update(text, 'utf8', 'base64');
  encrypted += cipher.final('base64');
  return iv.toString('hex') + ':' + encrypted;
}

function decrypt(encryptedText) {
  const [ivHex, data] = encryptedText.split(':');
  const iv = Buffer.from(ivHex, 'hex');
  const decipher = crypto.createDecipheriv('aes-256-cbc', Buffer.from(SECRET_KEY, 'hex'), iv);
  let decrypted = decipher.update(data, 'base64', 'utf8');
  decrypted += decipher.final('utf8');
  return decrypted;
}

// Store encrypted
await fetch('https://memforge.xyz/memory', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    key: 'secret-note',
    content: encrypt('My secret content'),  // ← encrypted
    metadata: { type: 'note', date: '2026-01-30' }  // ← searchable
  })
});

// Retrieve and decrypt
const res = await fetch('https://memforge.xyz/memory/secret-note', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const { data } = await res.json();
const plaintext = decrypt(data.content);
```

### Python

```python
import os
import base64
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.backends import default_backend

SECRET_KEY = bytes.fromhex(os.environ['MEMORY_ENCRYPTION_KEY'])  # 32 bytes

def encrypt(plaintext: str) -> str:
    iv = os.urandom(16)
    cipher = Cipher(algorithms.AES(SECRET_KEY), modes.CBC(iv), backend=default_backend())
    encryptor = cipher.encryptor()
    # Pad to 16 bytes
    padded = plaintext + (16 - len(plaintext) % 16) * chr(16 - len(plaintext) % 16)
    encrypted = encryptor.update(padded.encode()) + encryptor.finalize()
    return iv.hex() + ':' + base64.b64encode(encrypted).decode()

def decrypt(encrypted_text: str) -> str:
    iv_hex, data = encrypted_text.split(':')
    iv = bytes.fromhex(iv_hex)
    cipher = Cipher(algorithms.AES(SECRET_KEY), modes.CBC(iv), backend=default_backend())
    decryptor = cipher.decryptor()
    decrypted = decryptor.update(base64.b64decode(data)) + decryptor.finalize()
    # Remove padding
    pad_len = decrypted[-1]
    return decrypted[:-pad_len].decode()

# Usage
import requests

requests.post('https://memforge.xyz/memory',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'key': 'secret-note',
        'content': encrypt('My secret content'),
        'metadata': {'type': 'note'}  # searchable
    })
```

### Shell (using openssl)

```bash
# Generate a key (save this!)
KEY=$(openssl rand -hex 32)
echo "MEMORY_ENCRYPTION_KEY=$KEY" >> .env

# Encrypt
encrypt() {
  IV=$(openssl rand -hex 16)
  ENCRYPTED=$(echo -n "$1" | openssl enc -aes-256-cbc -K $KEY -iv $IV -base64)
  echo "$IV:$ENCRYPTED"
}

# Decrypt  
decrypt() {
  IV=$(echo "$1" | cut -d: -f1)
  DATA=$(echo "$1" | cut -d: -f2)
  echo "$DATA" | openssl enc -aes-256-cbc -d -K $KEY -iv $IV -base64
}

# Store
curl -X POST https://memforge.xyz/memory \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"key\": \"secret\", \"content\": \"$(encrypt 'my secret')\", \"metadata\": {\"type\": \"note\"}}"
```

### Key Management

```bash
# Generate a 256-bit key
openssl rand -hex 32
# → e.g. a1b2c3d4e5f6...

# Store securely:
# - Environment variable: MEMORY_ENCRYPTION_KEY
# - Secrets manager (AWS Secrets, Vault, etc.)
# - NEVER commit to git!
```

### What Gets Encrypted vs Searchable

| Field | Encrypted? | Searchable? | Example |
|-------|------------|-------------|---------|
| `content` | ✅ Yes | ❌ No | "My secret notes about..." |
| `metadata` | ❌ No | ✅ Yes | `{"type": "note", "date": "2026-01-30"}` |
| `key` | ❌ No | ✅ Yes | "meeting-notes-jan30" |

**Tip:** Put searchable keywords in metadata, sensitive content in encrypted `content`.

---

## Response Format

Success:
```json
{"success": true, "data": {...}}
```

Error:
```json
{"success": false, "error": "Description", "hint": "How to fix"}
```

---

## Rate Limits

- Free tier: 100 queries/day, 1 MB storage, 100 memories
- Paid tier: Unlimited

---

## Example: Save and Retrieve

```bash
# Register
curl -X POST https://memforge.xyz/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
# Save the api_key!

# Store a memory
curl -X POST https://memforge.xyz/memory \
  -H "Authorization: Bearer mk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "hello", "content": "Hello world!"}'

# Retrieve it
curl https://memforge.xyz/memory/hello \
  -H "Authorization: Bearer mk_YOUR_KEY"
```

---

## Need Help?

- Docs: https://memforge.xyz/docs
- API Status: https://memforge.xyz/health