CF Memory Plugin

Contributor: Hans Al Koch (HAK)
Canonical source: github.com/hansakoch/cf-memory-plugin · cloudflare-memory.pages.dev

Listings that scrape this repository are not the source.

Persistent memory for AI agents, backed by Cloudflare Agent Memory.

This plugin is a thin client. Cloudflare stores, classifies, and recalls memories. You do not run a vector DB, embeddings pipeline, or Worker.

Private beta. Expect 2-4 weeks for access after signing up. Paid Workers is required. Paid Workers alone is not enough — you still need Agent Memory entitlement.

One-Minute Setup

# 1. Install
pip install git+https://github.com/hansakoch/cf-memory-plugin.git

# 2. Set credentials (get these from Cloudflare dashboard)
export MCP_CLOUDFLARE_API_KEY="cf-api-token-with-agent-memory"
export CF_ACCOUNT_ID="your-32-char-account-id"

# 3. Verify everything works
cf-memory doctor

CF_ACCOUNT_ID is required. There is no default account. Find it in the Cloudflare dashboard sidebar.

Create the token at dash.cloudflare.com/profile/api-tokens with Agent Memory permission only. Do not reuse a Global API Key.

Verify it works

$ cf-memory doctor
cf-memory doctor — full diagnostic

1. Credentials
   ✓ MCP_CLOUDFLARE_API_KEY is set (cfut_W5...6d4e0)
   ✓ CF_ACCOUNT_ID is set (0870b0bd...)
   Namespace: hermes
   Profile:   default

2. Connectivity
   ✓ API reachable (0.8s)

3. Namespace
   ✓ Namespace 'hermes' exists

4. Profile & Memories
   ✓ Profile 'default' has 20 memories

5. Write/Read Test
   ✓ remember: 1.4s [fact] cf-memory doctor connectivity test
   ✓ recall:   3.2s — cf-memory doctor connectivity test
   ✓ cleanup:  test memory deleted

6. Latency Summary
   list_namespaces: 0.8s
   remember:        1.4s
   recall:          3.2s

──────────────────────────────────────────────────
✓ All checks passed — cf-memory is healthy

If anything fails, the output tells you exactly what to fix. See Troubleshooting for details.

Related MCP server: agentram-mcp

What's Stored

Memories live in namespaces (isolated buckets) and profiles (per-user or per-session views within a namespace).

Account
└── Namespace: "my-app"          ← one per project
    ├── Profile: "default"       ← general memories
    │   ├── Entry: "User prefers concise answers"
    │   ├── Entry: "Project uses PostgreSQL 16"
    │   └── Entry: "Deploy target is Fly.io"
    ├── Profile: "user:alice"    ← per-user context
    │   └── Entry: "Alice is in UTC+9"
    └── Profile: "session:xyz"   ← per-session scratch space
        └── Entry: "Currently refactoring auth module"

Each entry has:

• content — the raw text you stored

• summary — Cloudflare-generated one-liner

• type — classified category (fact, instruction, event, etc.)

• timestamps — createdAt, updatedAt

Use one namespace per app and one profile per user/tenant. Don't store secrets, passwords, or customer PII you aren't allowed to store.

What this is

MCP surface (token cost)

Harnesses (Grok CLI, Grok Bot, Claude, Codex, Cursor) inject every MCP tool schema into every turn, even if unused. Tool count and description size are the cost.

cf-memory serve and python -m cloudflare_memory advertise the full tool surface by default. Use cf-memory serve --slim for remember + recall only:

thinking_level and response_length are hardcoded to low / short. They are not MCP parameters.

Hermes does not use this MCP server. It uses the native memory provider (background ingest, non-blocking prefetch, zero MCP tools).

HTTP latency (client / CLI)

Each client call hits Cloudflare. Here's what to expect:

Cost: Agent Memory is free during private beta with 30-day notice before billing. You pay only for Workers Paid ($5/mo minimum). See Agent Memory pricing for post-beta rates.

Tip for Hermes users: Hermes prefetches memory in the background, so recall's ~5s latency doesn't block your turn.

A2A (Agent-to-Agent)

# Start A2A server
cf-memory a2a --port 9120

# Agent card available at
curl http://localhost:9120/.well-known/agent.json

The A2A server exposes remember and recall as agent skills. Any A2A-compatible agent can discover and call these tools.

MCP Config Examples

Same MCP block everywhere. Only the config file path changes. args: ["serve"] is the full default (all tools). Use ["serve", "--slim"] for remember + recall only.

Generic MCP block

{
  "mcpServers": {
    "cf-memory": {
      "command": "cf-memory",
      "args": ["serve"],
      "env": {
        "MCP_CLOUDFLARE_API_KEY": "your-token",
        "CF_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Grok CLI

Add to ~/.config/grok/mcp.json:

{
  "mcpServers": {
    "cf-memory": {
      "command": "cf-memory",
      "args": ["serve"],
      "env": {
        "MCP_CLOUDFLARE_API_KEY": "your-token",
        "CF_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Grok Bot

Set via environment variables before launch:

export MCP_CLOUDFLARE_API_KEY="your-token"
export CF_ACCOUNT_ID="your-account-id"

Or configure in your Grok Bot deployment's MCP server list using the generic block above.

Hermes

Hermes is the only native provider — zero MCP tools, so it does not pay the MCP schema tax. It prefetches in the background so recall does not add ~5s to every turn, and it ingests turns without blocking.

Single profile:

pip install git+https://github.com/hansakoch/cf-memory-plugin.git

# Add to ~/.hermes/.env
echo 'MCP_CLOUDFLARE_API_KEY=cfut_your_token' >> ~/.hermes/.env
echo 'CF_ACCOUNT_ID=your_account_id' >> ~/.hermes/.env

hermes config set memory.provider cloudflare-memory
hermes cloudflare-memory test

Multi-profile (hub + specialists):

Each profile has its own .env — the root .env does NOT propagate automatically.

# For EACH profile that needs memory access:
echo 'MCP_CLOUDFLARE_API_KEY=cfut_your_token' >> ~/.hermes/profiles/<name>/.env
echo 'CF_ACCOUNT_ID=your_account_id' >> ~/.hermes/profiles/<name>/.env
hermes --profile <name> config set memory.provider cloudflare-memory

Migrating old sessions: See docs/hermes-migration-guide.md for bulk ingest of existing session data.

Claude Code

claude mcp add cf-memory -- cf-memory serve

Or add to .claude/mcp.json:

{
  "mcpServers": {
    "cf-memory": {
      "command": "cf-memory",
      "args": ["serve"],
      "env": {
        "MCP_CLOUDFLARE_API_KEY": "your-token",
        "CF_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.cf-memory]
command = "cf-memory"
args = ["serve"]

[mcp_servers.cf-memory.env]
MCP_CLOUDFLARE_API_KEY = "your-token"
CF_ACCOUNT_ID = "your-account-id"

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cf-memory": {
      "command": "cf-memory",
      "args": ["serve"],
      "env": {
        "MCP_CLOUDFLARE_API_KEY": "your-token",
        "CF_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Other clients

Use it from Python

import asyncio
from cloudflare_memory import CloudflareMemoryClient

async def main():
    async with CloudflareMemoryClient(
        account_id="your-account-id",
        api_token="your-token",
        namespace="my-app",
        profile="default",
    ) as client:
        await client.remember("User prefers concise answers.")
        result = await client.recall("How should I answer?")
        print(result.answer)

asyncio.run(main())

CLI

cf-memory doctor                        # full diagnostic (run this first!)
cf-memory test                          # quick connectivity check
cf-memory serve                         # MCP (stdio): full tool surface
cf-memory serve --slim                  # MCP: remember + recall only
cf-memory list                          # list memories (CLI-only)
cf-memory get MEMORY_ID                 # get one memory (CLI-only)
cf-memory delete MEMORY_ID              # delete one memory (CLI-only)
cf-memory summary                       # markdown summary (CLI-only)
cf-memory ingest messages.json          # extract from a conversation (CLI-only)
cf-memory namespaces                    # list namespaces (CLI-only)
cf-memory create-ns NAME                # create a namespace (CLI-only)
cf-memory delete-ns NAME                # delete a namespace (CLI-only)
cf-memory a2a --port 9120               # A2A on localhost
cf-memory card                          # print agent card

hermes cloudflare-memory status
hermes cloudflare-memory namespaces

Run cf-memory doctor after setup — it checks credentials, connectivity, namespace, profile, memory count, and latency in one pass. If anything is broken, it tells you exactly what to fix.

ingest and summary stay on the CLI because registering them as MCP tools blows context on every turn.

Cost

Recommended: Workers Paid on the account that will hold memory. Do not put production memory on a free account. Do not assume every paid Workers account has Agent Memory — we verified paid ≠ entitlement.

After beta, treat Agent Memory as a separate bill. Cloudflare has not published GA rates yet.

Dependencies

Runtime:

Optional:

No Cloudflare Worker, Wrangler, D1, Vectorize, or Workers AI binding is required for this plugin. Those are Cloudflare products this client does not use.

Security

Follow Cloudflare's token rules: API token best practices.

• Store MCP_CLOUDFLARE_API_KEY in the environment or a secret store. Never commit it.

• Scope the token to Agent Memory on one account.

• Set CF_ACCOUNT_ID yourself. This plugin will not fall back to another account.

• cf-memory a2a binds to 127.0.0.1 by default. Do not expose it to the public internet without auth.

• ingest and sync_turn send conversation text to Cloudflare. Do not ingest secrets, passwords, or customer PII you are not allowed to store.

• Use one namespace per app and one profile per user/tenant.

• Rotate the token from the API Tokens page if it leaks.

See SECURITY.md.

Troubleshooting

cf-memory test fails with "Agent Memory not enabled"

Your account has Workers Paid but not the Agent Memory entitlement. This is a private beta — you need to join the waitlist and wait 2-4 weeks.

401 Unauthorized or 403 Forbidden

Your API token is missing the Agent Memory permission, or it's scoped to the wrong account. Create a new token at dash.cloudflare.com/profile/api-tokens with only Agent Memory selected.

CF_ACCOUNT_ID not set

Error: CF_ACCOUNT_ID is required

Find your 32-character account ID in the Cloudflare dashboard sidebar. Export it:

export CF_ACCOUNT_ID="abc123..."

cf-memory: command not found

The package isn't on your PATH. Try:

pip install --force-reinstall git+https://github.com/hansakoch/cf-memory-plugin.git

Or run it as a module: python -m cloudflare_memory (full MCP) or python -m cloudflare_memory serve --slim.

MCP client can't connect

• Ensure cf-memory is on PATH in the environment where the client runs. Some editors (Cursor, VS Code) use a different shell profile.

• Check the env block in your MCP config — typos in MCP_CLOUDFLARE_API_KEY or CF_ACCOUNT_ID are the most common issue.

• Test standalone first: cf-memory test.

recall is slow (~5s)

This is expected. recall does a semantic search then an LLM synthesis pass on Cloudflare's side. Hermes users get prefetching that hides this latency. For other clients, consider caching or calling recall asynchronously.

Ingested memories don't appear immediately

ingest returns immediately but Cloudflare extracts memories asynchronously. Wait 3–8 seconds, then call list or recall to verify.

Namespace already exists / doesn't exist

Error: namespace 'my-app' already exists

This is informational. Existing namespaces are fine — the plugin reuses them. If a namespace doesn't exist, create it:

# Via CLI (not an MCP tool — namespaces are not on the default server)
cf-memory create-ns my-app

# Or set it and it will be created on first write
export CF_MEMORY_NAMESPACE="my-app"

Rate limits

Cloudflare enforces API rate limits. If you see 429 Too Many Requests, back off and retry. The plugin automatically retries transient errors (429, 5xx) up to 3 times with exponential backoff.

MCP server crash loop (every 5 minutes)

If your agent logs show the MCP server failing and restarting every 5 minutes, the most common cause is missing dependencies in a sibling MCP server (not cf-memory itself). For example, a Node.js MCP server that was never npm installed.

Diagnosis:

# Check your agent's MCP stderr log
cat ~/.hermes/profiles/<profile>/logs/mcp-stderr.log | tail -20

# Look for: ERR_MODULE_NOT_FOUND, Cannot find package, etc.

Fix: Install the missing dependencies in the failing MCP server's directory, then restart your agent gateway. The cf-memory MCP server itself has no external dependencies beyond Python packages.

Prevention: Run cf-memory doctor after any config change — it validates the full stack in one pass.

cf-memory doctor — run this first

If anything feels broken, run the doctor:

cf-memory doctor

It checks:

1. Credentials (MCP_CLOUDFLARE_API_KEY, CF_ACCOUNT_ID)

2. API connectivity and auth

3. Namespace existence

4. Profile and memory count

5. Write/read round-trip with latency

6. Actionable error messages for every failure

Exit code 0 = healthy. Exit code 1 = something is wrong (the output tells you what).

Deploy the landing page (optional)

The plugin itself is not a Worker. The public page at cloudflare-memory.pages.dev is a static Cloudflare Pages site.

# token needs Pages:Edit on the same account
export CLOUDFLARE_API_TOKEN=...
export CLOUDFLARE_ACCOUNT_ID=...
npx wrangler pages deploy ./public --project-name cloudflare-memory --commit-dirty=true

Pages docs · Wrangler

Credits

• Contributor: Hans Al Koch (HAK)

• Canonical source: github.com/hansakoch/cf-memory-plugin. Listings that scrape this repository are not the source.

• Memory backend: Cloudflare Agent Memory (blog, Discord, Community)

• Protocol: Model Context Protocol

• Hermes provider contract: Nous Research Hermes Agent

• HTTP client: httpx

• Design inspiration: Open Brain (OB1) — "One database, one AI gateway, one chat channel — any AI plugs in."

This repo is not affiliated with Cloudflare or Nous Research.

License

MIT

MCP Compatibility

mcp 1.26.0+

If you get ModuleNotFoundError: No module named 'mcp.server.mcpserver', the fix is already applied in this repo. The server uses FastMCP instead of MCPServer.

Older mcp versions

If you have mcp < 1.0, you may need to update:

pip install --upgrade mcp

Multi-Agent Setup (All Profiles)

Automatic Configuration

When installing cf-memory-plugin, configure ALL Hermes profiles:

# For each profile in ~/.hermes/profiles/:
for profile in $(ls ~/.hermes/profiles/); do
  # Set memory provider
  hermes --profile $profile config set memory.provider cloudflare-memory
  
  # Add MCP server
  cat >> ~/.hermes/profiles/$profile/config.yaml << 'MCP'
mcp:
  servers:
    cf-memory:
      command: cf-memory
      args: ["serve"]
      env:
        MCP_CLOUDFLARE_API_KEY: ${MCP_CLOUDFLARE_API_KEY}
        CF_ACCOUNT_ID: ${CF_ACCOUNT_ID}
MCP
  
  # Add vision support
  current=$(hermes --profile $profile config get toolsets 2>/dev/null)
  if ! echo "$current" | grep -q "computer_use"; then
    hermes --profile $profile config set toolsets "$current,computer_use"
  fi
  
  # Remove old memory toolset (prevents using local memory)
  current=$(hermes --profile $profile config get toolsets 2>/dev/null)
  if echo "$current" | grep -q "memory"; then
    new=$(echo "$current" | sed 's/,memory//g' | sed 's/memory,//g')
    hermes --profile $profile config set toolsets "$new"
  fi
done

SOUL.md Migration

Store all SOUL.md files in CF memory for cross-agent access:

python3 << 'PYEOF'
import asyncio, os, glob
from cloudflare_memory import CloudflareMemoryClient

async def main():
    async with CloudflareMemoryClient(
        account_id=os.environ["CF_ACCOUNT_ID"],
        api_token=os.environ["MCP_CLOUDFLARE_API_KEY"],
        namespace="hermes",
        profile="default",
    ) as client:
        for soul_path in glob.glob(os.path.expanduser("~/.hermes/profiles/*/SOUL.md")):
            profile_name = soul_path.split("/")[-2]
            with open(soul_path, "r") as f:
                content = f.read()
            await client.remember(f"[SOUL.md:{profile_name}] {content[:2000]}")
            print(f"Stored SOUL.md for {profile_name}")

asyncio.run(main())
PYEOF

Multi-Device Access

CF memory is accessible from any device with:

• API token (MCP_CLOUDFLARE_API_KEY)

• Account ID (CF_ACCOUNT_ID)

Configure each device's agents with the same credentials.

Export Data

python3 << 'PYEOF'
import asyncio, os, json
from cloudflare_memory import CloudflareMemoryClient

async def main():
    async with CloudflareMemoryClient(
        account_id=os.environ["CF_ACCOUNT_ID"],
        api_token=os.environ["MCP_CLOUDFLARE_API_KEY"],
        namespace="hermes",
        profile="default",
    ) as client:
        entries = await client.list_memories(per_page=100)
        export = [{"id": e.id, "type": e.type, "summary": e.summary} for e in entries]
        with open("cf-memory-export.json", "w") as f:
            json.dump(export, f, indent=2)
        print(f"Exported {len(entries)} memories")

asyncio.run(main())
PYEOF