Skip to content

feat(agent-memory): add account-scoped Agent Memory MCP server - #417

Draft
jonnyparris wants to merge 2 commits into
cloudflare:mainfrom
jonnyparris:add-agent-memory-mcp
Draft

feat(agent-memory): add account-scoped Agent Memory MCP server#417
jonnyparris wants to merge 2 commits into
cloudflare:mainfrom
jonnyparris:add-agent-memory-mcp

Conversation

@jonnyparris

@jonnyparris jonnyparris commented Jul 17, 2026

Copy link
Copy Markdown
Member

What

Adds apps/agent-memory, an account-scoped MCP server for persistent, semantically searchable agent memory.

Files live in an R2 bucket (agent-memory-mcp) in the selected Cloudflare account. Embeddings and on-demand reflection use Workers AI in that same account, so storage and inference are billed there. Search metadata lives in one Durable Object per account (idFromName(accountId)), matching the R2 isolation boundary.

Tools (22)

  • Files: read, write, write_many, reindex, list, list_tags, get_backlinks
  • Search: search
  • Conversations: search_conversations, index_conversations, expand_conversation, conversation_stats
  • Reminders: schedule_reminder, list_reminders, remove_reminder, check_reminders
  • Reflection: run_reflection, list_pending_reflections, apply_reflection_changes, archive_reflection
  • Config: get_config, set_config

Design and safety

  • Uses the shared @repo/mcp-common OAuth/account helpers and accountTool account selection.
  • Uses the standard MCP deployment account plus the shared staging/production OAuth KV namespaces.
  • Keeps Cloudflare credentials out of Durable Object storage: embeddings are generated before DO RPC calls.
  • Validates and encodes R2 object paths, preventing .. path normalization from escaping the dedicated bucket.
  • Reserves internal paths (.mcp/, conversations, reminders, reflection metadata) for dedicated tools and redacts webhook secrets from config responses.
  • Uses a bounded, deterministic exact-cosine vector index (5,000 entries) with SQLite persistence, tag/scope filtering, binary vectors, and a repair-oriented reindex tool.
  • Bounds object size, directory listings, search results, batch concurrency, conversation payloads, reminders, reflection iterations, and model tool calls.
  • Reflection is on-demand and opt-out. Low-risk fixes may be applied immediately; substantive edits remain pending for review. Source hashes prevent approved edits from overwriting files changed after reflection, and an account-level lock prevents concurrent reflection runs.
  • Webhooks are bounded by timeout, reject redirects, and expose only their host through get_config.
  • Removes unsupported history/rollback tools rather than advertising no-op behavior.

Account members with the required permissions share the account's memory; this is documented in the server instructions and README.

Deployment

  • Staging: memory-staging.mcp.cloudflare.com
  • Production: memory.mcp.cloudflare.com
  • Both Streamable HTTP (/mcp) and legacy SSE (/sse) are registered in server.json.

OAuth client credentials and the cookie-encryption secret remain Wrangler secrets, consistent with the other authenticated MCP servers.

Verification

  • pnpm check:deps
  • pnpm check:turbo — 41/41 tasks ✅
  • pnpm check:format
  • pnpm test — 29 files / 281 tests ✅
  • Agent Memory suite — 18 files / 162 tests ✅
  • Staging deploy dry-run ✅
  • Production deploy dry-run ✅

jonnyparris and others added 2 commits July 17, 2026 15:42
Persistent, semantically searchable memory for agents, backed by the
authenticated user's own R2 bucket and Workers AI (billed to their
account via the Cloudflare REST API).

- File read/write with YAML-tag and [[wikilink]] indexing
- Semantic search over files and indexed conversations
- Reminders
- On-demand agentic reflection (opt-out; no background cron)
- Generic notification webhook configured via set_config
- Per-user HNSW vector index in a Durable Object (idFromName(userId))

OAuth built-in via @cloudflare/workers-oauth-provider using shared
@repo/mcp-common helpers.
Align storage and index isolation with the selected account, use the shared MCP deployment account/KV, prevent R2 path escape, stage substantive reflection edits with optimistic concurrency checks, and bound resource usage.\n\nReplace the mutable HNSW prototype with a deterministic bounded vector index and add unit/DO regression coverage for storage, search, conversations, reminders, reflection, and tool schemas.
@mattzcarey mattzcarey changed the title feat(agent-memory): add Agent Memory MCP server feat(agent-memory): add account-scoped Agent Memory MCP server Jul 17, 2026
@mattzcarey

Copy link
Copy Markdown
Collaborator

Keeping this PR in draft. Staging is deployed, but normal browser OAuth is not functional yet.

Blocked until a dedicated OAuth client is provisioned with the Agent Memory staging/production callback URLs and the corresponding Worker secrets are installed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants