agent-memory-mcp

Give your AI coding assistant a long-term memory.

AI assistants like Claude Code, Cursor, and OpenCode forget everything between sessions. This fixes that. agent-memory-mcp is a small server you deploy to your own Cloudflare account that stores memories, searches them by meaning, and keeps them organized -- so your AI gets smarter the longer you use it.

It runs entirely on Cloudflare's free tier. Your data never leaves your account.

What can you do with it?

Some real examples:

• "Always use pnpm, not npm" -- Tell your AI once. It remembers in every future session.

• "How did I fix that CORS bug last week?" -- Search past conversations by meaning, not keywords.

• "Alice owns the auth service" -- Your AI knows who to ask about what.

• "We decided to use REST, not GraphQL" -- Project decisions persist across sessions.

• "Port 8787 is already used by wrangler" -- Your AI won't make the same mistake twice.

Related MCP server: MCP Memory

How it works

1. Write -- Your AI saves a note (a preference, a lesson, a decision).

2. Store -- The file is saved to R2 with full version history. You can roll back any change.

3. Index -- Workers AI turns the text into a vector embedding and adds it to a searchable index.

4. Search -- Later, your AI (or you) can find that memory by asking a question in plain English. Semantic search matches by meaning, not exact words.

Recent memories rank higher than old ones automatically.

Architecture

Three Cloudflare services, one Worker:

Quick start

Option A: One-click deploy

Click the button, follow the prompts, and you'll have a running server in under 2 minutes:

After deploying, set your auth token:

npx wrangler secret put MEMORY_AUTH_TOKEN
# Enter a secure random token when prompted

Option B: Clone and deploy manually

git clone https://github.com/jonnyparris/agent-memory-mcp.git
cd agent-memory-mcp
npm install

# Create your R2 bucket
npx wrangler r2 bucket create agent-memory

# Set your auth token
npx wrangler secret put MEMORY_AUTH_TOKEN
# Enter a secure random token when prompted

# Deploy
npm run deploy

Connect your AI assistant

Once deployed, connect your AI assistant to the server. Replace YOUR_SUBDOMAIN with your Cloudflare Workers subdomain (find it in the Cloudflare dashboard under Workers & Pages).

Claude Code

export MEMORY_AUTH_TOKEN="your-secret-token"
claude mcp add --transport http agent-memory \
  https://agent-memory-mcp.YOUR_SUBDOMAIN.workers.dev/mcp \
  --header "Authorization: Bearer $MEMORY_AUTH_TOKEN"

Cursor

Go to Settings > MCP Servers > Add:

• URL: https://agent-memory-mcp.YOUR_SUBDOMAIN.workers.dev/mcp

• Headers: Authorization: Bearer YOUR_TOKEN

OpenCode

Add to .opencode/opencode.json:

{
  "mcp": {
    "agent-memory": {
      "type": "remote",
      "url": "https://agent-memory-mcp.YOUR_SUBDOMAIN.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer {env:MEMORY_AUTH_TOKEN}"
      }
    }
  }
}

Any MCP-compatible client

The server speaks the standard Model Context Protocol. Any MCP client can connect via HTTP with a Bearer token header.

Available tools

The server exposes 23 MCP tools. Your AI assistant discovers and uses them automatically -- you don't need to call them yourself.

Core memory

Conversations

Reminders

Reflection

Recommended memory structure

You can organize your memory however you like. Here's a structure that works well:

memory/
├── learnings.md        # Lessons learned, gotchas, corrections
├── preferences.md      # Your coding style, tool preferences
├── people.md           # Teammates, roles, availability
├── projects.md         # Active projects, architecture decisions
│
├── patterns/           # Reusable patterns and templates
│   ├── git.md
│   ├── code-review.md
│   └── debugging.md
│
├── workload/           # Current tasks and priorities
│   ├── active.md
│   ├── backlog.md
│   └── archive/
│
└── archive/            # Old context you might need someday

Scheduled reflection

The server includes an automated self-improvement system. Every day at 6am UTC, it reviews your memory files and cleans them up.

Quick scan (GLM 4.7 Flash) catches simple issues -- typos, broken formatting, duplicate entries -- and fixes them automatically.

Deep analysis (Moonshot Kimi K2.6, 262k context, agentic) looks for contradictions, outdated information, gaps, orphaned files, and missing cross-references. It proposes changes for you to review, including adding [[wikilinks]] where files clearly relate but don't reference each other. It uses the backlink index to understand which files are hubs and which are orphans before proposing merges or deletes.

Override the defaults with REFLECTION_MODEL and REFLECTION_MODEL_FAST in wrangler.jsonc or as secrets if you want to try a different pair.

You get a notification summary after each run. You can also trigger it manually:

curl -X POST "https://your-worker.workers.dev/reflect" \
  -H "Authorization: Bearer YOUR_TOKEN"

What the scheduled reflection is not

The cron-driven reflection is a lightweight, autonomous scan. It runs unattended on a budget of a few iterations and writes proposals to memory/reflections/pending/{date}.md (empty proposals get archived to memory/reflections/archive/{date}.md to make zero-output runs visible).

This is not the same as a deep reflection workflow you might drive from your agent — e.g. a /nightly-reflect slash command that pulls your entire week of activity (calendar, git log, scratch notes, chat history) and writes a multi-section improvement plan. The cron has none of that context. It only sees what's already in memory.

Concretely:

• Cron output lives in memory/reflections/pending/ and memory/reflections/archive/. Expect terse summaries and small auto-fixes.

• Agent-driven deep reflection output should live somewhere else (e.g. memory/workload/plans/{date}-improvement-proposals.md). Don't conflate the two — a healthy memory/reflections/archive/ does not mean your weekly reflection ran.

If your agent has a separate deep-reflection workflow, watch its output directory directly. The cron is a janitor; the agent is the architect.

The execute tool

The execute tool runs arbitrary JavaScript against your memory. It's fast and convenient for complex queries (group files by tag, aggregate word counts, etc.) but it's not a sandbox:

• Code runs in the same V8 isolate as the Worker.

• It has access to global fetch, crypto, and other Web APIs.

• It runs with the Worker's CPU limit as the only time bound (plus a 10s wall-clock timeout from the tool).

• It does NOT have access to env bindings, your auth token, or other secrets — those never touch the global scope.

Guidance:

1. Only use execute when you trust who's calling it. The auth token protects the MCP endpoint; anyone with the token can run code.

2. Don't expose this MCP to untrusted users without stripping the execute tool first.

3. Use search + read instead when you can — they're safer and usually faster.

Cost

Runs entirely within Cloudflare's free tier for personal use:

Total: $0/month

Development

npm install       # Install dependencies
npm run dev       # Run locally
npm test          # Run all tests
npm run test:unit # Unit tests only
npm run deploy    # Deploy to Cloudflare

Migrating existing memory files

If you have local memory files you want to upload:

npm run migrate   # Upload local files to your deployed server
npm run export    # Download all files from the server to local disk

License

MIT