← All articles

Base memory usage

A freshly started Paperclip server uses approximately:

• Node.js runtime: 50–80 MB
• Paperclip server process: 80–150 MB
• SQLite in-memory cache: 20–50 MB

Total at idle: ~150–280 MB

This is what you'll see with no agents running and no active sessions.

Memory during agent heartbeats

When agents run, memory usage climbs:

• Each concurrent Claude agent run: +50–150 MB (spawns a Claude Code subprocess)
• Database operations: Spikes of 20–50 MB during complex queries
• File operations (agent workspaces): Depends on file sizes and operations

With 3 agents running concurrently, expect 400–700 MB peak usage.

Recommended RAM by use case

| Scenario | Recommended RAM | |---|---| | Local development, no agents | 512 MB | | Personal use, 1–2 agents | 1 GB | | Small team, 5 agents | 2 GB | | Active team, 10+ concurrent agents | 4 GB | | Large team with heavy workloads | 8 GB+ |

Signs you're running out of memory

OOM kills: The Linux kernel kills the Paperclip process when RAM runs out. You'll see restarts in journalctl -u paperclip with exit code -9 or Killed messages.

Slow performance: Heavy swap usage (Paperclip writing to disk instead of RAM) makes everything slow. Check: free -h to see if swap is in use.

Agent heartbeats timing out: If the process is swapping, heartbeat runs may exceed their time limits.

Check current memory usage:

free -h
ps aux --sort=-%mem | head -10

How to reduce memory usage

Limit concurrent runs per agent:

In Paperclip's agent settings, reduce maxConcurrentRuns to 1. This prevents multiple heartbeats from spawning simultaneously:

{
  "runtimeConfig": {
    "heartbeat": {
      "maxConcurrentRuns": 1
    }
  }
}

Pause inactive agents: Agents that aren't actively needed can be paused from the dashboard. A paused agent doesn't run heartbeats, freeing up resources.

Increase swap space:

Not a long-term fix, but buys time on low-memory servers:

# Create a 1 GB swap file
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Upgrade your server: Usually the right answer. Going from 1 GB to 2 GB RAM typically costs $5–7/month more and solves memory pressure completely.

Node.js memory limits

Node.js has a default heap limit of ~1.5 GB on 64-bit systems. If Paperclip itself is consuming this much RAM, something unusual is happening (a memory leak or very heavy data processing). For most deployments you won't hit this limit.

If needed, you can adjust it in the Paperclip start command:

node --max-old-space-size=2048 $(which paperclipai) server start

This sets the Node.js heap to 2 GB. Only do this if you've confirmed Paperclip itself (not agents) is consuming excessive memory.

Monitoring memory

Real-time:

htop  # Interactive process viewer
watch -n 5 free -h  # Update every 5 seconds

Historical (if using systemd):

journalctl -u paperclip --since "1 hour ago" | grep -i "memory\|oom\|kill"

Per-container (Docker):

docker stats paperclip

Memory on different VPS plans

| Provider | Plan | RAM | Fits Paperclip? | |---|---|---|---| | Hetzner | CX11 | 2 GB | Yes, comfortably | | Linode | Nanode | 1 GB | Yes, tight | | DigitalOcean | Basic | 1 GB | Yes, tight | | Contabo | VPS S | 8 GB | Yes, with room for 10+ agents | | Fly.io | shared-cpu-1x | 256 MB | No — upgrade to 1 GB | | Railway | Starter | 8 GB | Yes |

The 256 MB Fly.io default is too small. Always upgrade to at least 512 MB, preferably 1 GB.

Paperclip vs. self-hosted memory efficiency

Paperclip's memory footprint is comparable to other Node.js platforms like Notion or Linear's self-hosted versions. The agent subprocess model (spawning Claude Code per heartbeat) adds overhead compared to in-process AI calls, but it provides better isolation and security.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.