Hermes Agent Memory Cloudflare MCP

赫尔墨斯记忆云焰

Cloudflare边缘的结构化代理内存 赫尔墨斯代理.

受到启发 赫尔墨斯记忆 Mibayy——一个我们使用和推荐的坚固的本地SQLite内存MCP。我们想要相同类型的结构化内存，但由Cloudflare支持，这样它就可以在机器故障和跨设备同步时幸存下来。这是一个独立的实现，而不是分叉——不同的模式、不同的工具、不同的设计。两者既可以并行运行，也可以独立运行。

单个Python文件。十五个工具。通过stdio在本地运行，通过Cloudflare D1和R2远程存储。

______________________________________________________________________

运作原理

Hermes Agent (stdio)
  └─ server.py
       ├──► Cloudflare D1 REST API
       │      memories   — facts, decisions, constraints, values
       │      scopes     — topic groupings that auto-cool when idle
       │      sessions   — turn counter, active scope, read/write stats
       │      gauge      — pressure meter: how full is active memory (0-100%)
       │      (SQLite on the edge, 5M reads/day free)
       │
       └──► Cloudflare R2 REST API
              snapshots  — named backups of full memory state, restorable
              (10GB free, zero egress fees)

服务器作为子进程在本地运行。Hermes创造了它，发现了15个工具，并通过stdio调用它们。所有数据都通过HTTPS流向Cloudflare——没有Worker部署，没有Wrangler，也没有Node.js。

D1是边缘的无服务器SQLite。您的记忆存储在一个数据库中，可以从任何具有凭据的计算机访问。R2保存快照——您可以从中恢复的完整导出。首次使用时自动创建架构，版本之间的升级是自动的。

______________________________________________________________________

它看起来像什么

存储内存

→ memory_store(content="PostgreSQL for auth service", type="decision", scope="auth")

← { "stored": true, "id": "018e1a2b...", "type": "decision",
     "scope": "auth", "source": "profile:coder" }

# Same scope+type → old one is superseded automatically
→ memory_store(content="MySQL for auth service", type="decision", scope="auth")

← { "stored": true, "id": "018e1c...", "conflict_resolved": "018e1a2b..." }

# Identical content → deduplicated, no new memory created
→ memory_store(content="MySQL for auth service", type="decision", scope="auth")

← { "stored": false, "status": "dedup", "id": "018e1c..." }

搜索

→ memory_search(query="database", scope="auth")

← { "count": 2, "results": [
     { "content": "MySQL for auth service", "type": "decision", "status": "active" },
     { "content": "UUID primary keys mandatory", "type": "constraint", "status": "active" }
   ]}

会话生命周期

# Session start — get gauge, active scopes, hot memories
→ memory_status(session_id="sess-001")

← { "gauge": {"used_chars": 3200, "max_chars": 10000, "pct": 32.0},
     "active_scopes": [{"label": "auth", "current_turn": 4}],
     "hot_memory_count": 12 }

# Every turn — advance counter, trigger scope cooling + gauge
→ memory_tick(turn=5, session_id="sess-001", message="deployed the auth service")

← { "turn": 5, "scopes_cooled": ["018e1a..."], "gauge_actions": [] }

健康检查

→ memory_health()

← { "gauge": {"pct": 85.0},
     "stale_count": 3, "superseded_count": 7,
     "suggestions": [
       "Memory gauge at 85.0% — consider archiving old memories.",
       "7 superseded memories. Run memory_forget(hard=True) to purge."
     ]}

快照

→ snapshot_create(name="before-refactor")
← { "created": true, "memory_count": 47, "size_bytes": 12840 }

→ snapshot_restore(id="018e1b...", strategy="merge")
← { "restored": true, "imported": 12, "skipped": 35 }

______________________________________________________________________

设置

1.安装依赖项

pip install -r requirements.txt

2.创建Cloudflare资源

在 Cloudflare仪表板:

1. D1数据库 （必填）：存储和数据库>D1>创建数据库。复制数据库ID。
2. R2铲斗 （可选--仅适用于快照）：存储和数据库>R2>创建存储桶。
3. API代币：我的个人资料>API代币>创建自定义代币

- 许可： 账户/D1/编辑 （必填） - 许可： 帐户/R2/编辑 （仅当使用快照时）

3.运行安装程序

python3 setup.py           # default profile
python3 setup.py coder     # named profile

引导您浏览每个凭证，并提示在哪里可以找到它们。写 .env 和 config.yaml 直接打印或手动打印。R2是可选的。

4.验证

hermes mcp test hermes-memory-cloudflare
# ✓ hermes-memory-cloudflare: connected (15 tools available)

5.迁移现有内存（可选）

如果你有 赫尔墨斯记忆 安装了事实 memory.db，导入它们：

python3 migrate.py           # default profile
python3 migrate.py coder     # named profile

阅读您的本地 memory.db，将事实和范围映射到cloudflare模式中，上传到D1，并创建R2快照。多次运行是安全的——重复的内容会被跳过。您当地的 memory.db 未被修改。

Manual setup (non-Hermes clients)

将凭据添加到 .env:

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_D1_DATABASE_ID=your-d1-database-id
# CLOUDFLARE_R2_BUCKET=mcp-memory-snapshots  # optional

添加到Hermes config.yaml:

mcp_servers:
  hermes-memory-cloudflare:
    command: "python3"
    args: ["/path/to/hermes-memory-cloudflare/server.py"]
    env:
      CLOUDFLARE_ACCOUNT_ID: "${CLOUDFLARE_ACCOUNT_ID}"
      CLOUDFLARE_API_TOKEN: "${CLOUDFLARE_API_TOKEN}"
      CLOUDFLARE_D1_DATABASE_ID: "${CLOUDFLARE_D1_DATABASE_ID}"
      CLOUDFLARE_R2_BUCKET: "${CLOUDFLARE_R2_BUCKET}"
    timeout: 30
    connect_timeout: 15

对于Claude Desktop/Cursor/VS Code，将凭据直接放入MCP JSON配置中（这些客户端没有 .env 支持）。

______________________________________________________________________

工具

分为五组的十五种工具：

______________________________________________________________________

演出

每次工具调用都是到Cloudflare的HTTPS往返，没有缓存。服务器避免了这种情况：

• 快照种子本地缓存。 如果配置了R2快照， memory_status 在第一次调用时下载最新快照并将其加载到内存中。所有后续阅读(memory_search, memory_recall, memory_reflect, memory_stats)点击本地缓存——零网络延迟。写入操作同时进入本地缓存和D1（直写）。这将一个会话从数十个HTTPS调用转换为一个初始下载+后台同步。
• 持久HTTP客户端。 一个与D1写入保持活动的连接。每次调用都没有TCP+TLS握手。
• 排队写入刷新。 当本地存储处于活动状态时，写入将按小组排队和刷新，而不是对每个突变强制进行网络调用。
• 顺序多语句助手。 _d1_batch() 与组相关的SQL在一个助手后面工作，但D1REST仍然将这些语句作为连续的HTTP请求执行。这使得调用代码更简单，并让缓存完全避免了许多这样的调用。
• 访问日志批处理。 在内存中排队，每10个条目刷新一次或 memory_tick.
• 懒惰的仪表。 压力检查仅在写入后运行，而不是在每个刻度后运行。
• 架构版本控制。 当模式为当前模式时跳过init（1次查询检查）。

必须知道：

• memory_tick 每一个转弯都应该被召唤。它驱动示波器冷却和仪表维护。
• 如果Cloudflare无法访问，则从本地缓存读取工作。写入队列并重试。
• 启用快照后，服务器会在会话结束时自动快照以保持R2最新。
• 在没有配置R2的情况下，一切都直接通过D1（使用批处理+持久客户端仍然很快）。

______________________________________________________________________

技能

附带的一项技能告诉代理如何在预期的主要模式中使用工具：

通过复制到您的Hermes技能目录进行安装：

cp -r skills/use-cloudflare-memory ~/.hermes/skills/hermes-memory-cloudflare-primary

Using with hermes-memory (dual memory setup)

两个MCP可以并行运行。没有工具名称冲突——Hermes会自动为它们命名(mcp_hermes_memory_* 对比 mcp_hermes_memory_cloudflare_*).

此回购仅发货 使用cloudflare内存 技能。如果运行两个MCP，请明确cloudflare是主要的持久内存系统，这样代理就不会在两个内存后端之间任意切换。

______________________________________________________________________

Hermes Profiles

爱马仕简介 让您运行多个独立的代理。hermes memory cloudflare检测活动配置文件并自动标记存储器 source: "profile:".

每个配置文件的独立内存（推荐）： 每个配置文件 .env 指向不同的D1数据库。

# ~/.hermes/profiles/coder/.env
CLOUDFLARE_D1_DATABASE_ID=d1-id-for-coder

# ~/.hermes/profiles/research/.env
CLOUDFLARE_D1_DATABASE_ID=d1-id-for-research

共享内存： 相同的D1数据库，内存自动标记配置文件名称。

交叉设备： 笔记本电脑和VPS上的配置文件相同，D1数据库相同。不需要同步。

______________________________________________________________________

未来的潜力

数据存储在Cloudflare中。有几件事在不重新架构的情况下变得简单明了：

• 将语义搜索矢量化。 Cloudflare矢量化用于矢量相似性，Workers AI用于嵌入(bge-base-en-v1.5768d）。在商店：嵌入+索引。搜索：关键字（D1）+矢量（矢量化），合并和排名。“查找关于身份验证的记忆”即使在任何记忆中都没有“身份验证”这个词，也能正常工作。通过env-var选择加入，免费层覆盖它（每月查询30M个dims，每天10K个神经元）。
• 工人部署。 将MCP作为Cloudflare Worker运行——任何设备都可以通过HTTP连接，不需要本地Python。
• D1时间旅行。 时间点恢复最多30天。R2快照旁边的独立恢复路径。
• 信心衰退。 这 confidence 字段存在。未来：可配置的衰减率，低阈值自动存档。

______________________________________________________________________

发展

pip install -r requirements.txt
python3 tests/test_server.py

96次测试。所有这些都被嘲笑了——不需要Cloudflare凭据。

项目结构

hermes-memory-cloudflare/
  server.py              # 15 tools, single file
  setup.py               # Interactive setup
  migrate.py             # Import from local hermes-memory (memory.db)
  requirements.txt
  .env.example
  tests/test_server.py   # 96 tests
  skills/use-cloudflare-memory/SKILL.md
  REQUIREMENTS.md        # Design doc
  CHANGELOG.md
  README.md

依赖关系：Python 3.10+， mcp[cli], httpx没有Workers，没有Wrangler，没有Node.js。

______________________________________________________________________

链接

• 赫尔墨斯代理 --这是为代理而构建的
• 赫尔墨斯记忆 作者Mibayy——启发这个项目的本地SQLite内存MCP
• 爱马仕简介指南

______________________________________________________________________

许可证

麻省理工学院