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.

Need	Link
Join the beta (2-4 week wait)	Waitlist form
Product docs	developers.cloudflare.com/agent-memory
HTTP API	HTTP API
Pricing	Agent Memory pricing
Limits	Platform limits
Create a token	API Tokens
Create a token (docs)	Create API token
Workers Paid	Workers pricing
Design notes	Introducing Agent Memory

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.

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"

Concept	Default	Override
Namespace	`hermes`	`CF_MEMORY_NAMESPACE` env or `--namespace` flag
Profile	`default`	`CF_MEMORY_PROFILE` env or `--profile` flag

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

You call	Cloudflare does	Default MCP
`remember`	Store one fact / instruction / event	yes
`recall`	Search + synthesize an answer (~5s)	yes
`ingest`	Extract memories from a conversation (writes land 3–8s later)	yes (omit with `--slim`)
`summary`	Markdown profile of what is stored	yes (omit with `--slim`)
`list` / `get` / `delete`	Inspect or remove entries	yes (omit with `--slim`)

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:

Tool	Schema	Returns	Default	`--slim`
`remember`	`content: str`	compact `{"id","type"}`	yes	yes
`recall`	`query: str`	short synthesized answer only	yes	yes
admin tools	list/get/delete/ingest/summary/namespaces	varies	yes	no

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:

Call	Latency	What happens
`remember`	~2s (1.3–3.8s)	Classify + store one memory
`recall`	~5s	Semantic search + LLM synthesis of answer
`ingest`	~3s + async	Accept messages, return immediately. Cloudflare extracts memories in the background (3–8s)
`summary`	~1s	Fetch the generated markdown profile
`list`	~0.4s	Fast pagination, no content
`get`	~1.4s	Single entry with content
`delete`	~1s	Remove by ID

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

Agent	Where to put it	Docs
OpenClaw	host MCP config	OpenClaw
TRAE	`.trae/mcp.json`	TRAE
OpenCode	`~/.opencode/config.json`	OpenCode
pi	host MCP config	pi
Any MCP client	stdio `cf-memory serve`	MCP spec
LangChain / LangGraph	Python `CloudflareMemoryClient`	LangChain
A2A peers	`cf-memory a2a --port 9120`	Agent card at `/.well-known/agent.json`

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

Item	Today	Source
Agent Memory	$0 during private beta. 30-day notice before billing.	Pricing
Workers Paid (required to apply)	$5/month minimum	Workers pricing
This plugin	Free (MIT). Your own HTTP calls only.	—

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:

Package	Why
httpx	HTTPS client to `api.cloudflare.com`
mcp	MCP server (`cf-memory serve`)

Optional:

Extra	Packages	When
`pip install 'cf-memory-plugin[a2a]'`	starlette, uvicorn	A2A peer server
`pip install 'cf-memory-plugin[dev]'`	pytest, pytest-asyncio, respx	Tests

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:

Credentials (MCP_CLOUDFLARE_API_KEY, CF_ACCOUNT_ID)
API connectivity and auth
Namespace existence
Profile and memory count
Write/read round-trip with latency
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

Name		Name	Last commit message	Last commit date
docs		docs
public		public
scripts		scripts
src/cloudflare_memory		src/cloudflare_memory
tests		tests
.gitignore		.gitignore
CITATION.cff		CITATION.cff
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation