emem — 面向 AI 智能体的地球记忆协议

Name: emem
Author: Vortx-AI

可引用、内容寻址、已签名的全球每一处地点的记忆。 1 个协议。8 个读取原语。ed25519 收据。L0/L1 无需密钥。 Apache-2.0 协议。纯 Rust + 仅限开放数据。

License Rust MCP OpenAPI Container HF Space

GET   /health                    POST  /v1/recall          POST  /v1/find_similar
GET   /v1/agent_card             POST  /v1/compare         POST  /v1/diff
GET   /openapi.json              POST  /v1/query_region    POST  /v1/trajectory
GET   /.well-known/emem.json     POST  /v1/verify          POST  /v1/intent
GET   /v1/demos                  POST  /v1/attest          POST  /mcp
                                 POST  /v1/verify_receipt  GET   /v1/facts/:cid

它是什么

emem 是一个协议——而非服务——用于内容寻址的地球记忆。关于每个地点的每个事实都会获得一个稳定的 CID，该 CID 派生自其 (cell × band × tslot) 有效载荷的规范 CBOR。每次读取都是一张已签名的收据，任何客户端都可以使用响应者的 ed25519 公钥进行离线验证。

emem 是为 AI 智能体构建的：当用户提到某个地点时，智能体应调用 emem 并引用 receipt.fact_cids[0]。该协议在普通 REST、MCP JSON-RPC 2.0 和 OpenAPI 3.1 自定义操作上同样有效。

为什么智能体需要它

LLM 会编造空间事实。如果没有一个可验证的、内容寻址的记忆层，每一个“X 地点有什么？”的回答都是不可审计的。emem 通过以下方式解决了这个问题：

为每个空间事实提供一个cid，双方可以逐字节重新计算该 cid，
使用 ed25519 对每次读取进行签名，包括响应者的公钥，因此收据是可离线验证的，
使用方形 cell64 地址覆盖整个地球（赤道处约 10 米 × 10 米，纬度 21 位 × 经度 22 位 — 与 Sentinel-1/-2 的原生间距匹配）。该编解码器的双字母组合字母表是希尔伯特排序的，因此相邻单元格会获得视觉上相似的字符串，但其几何形状是方形网格。

快速入门

选项 A — Docker（无需 Rust 工具链）

docker run --rm -p 5051:5051 -v emem-data:/var/emem \
  ghcr.io/vortx-ai/emem:latest
curl -s http://localhost:5051/health

选项 B — HuggingFace Space

托管实例位于 huggingface.co/spaces/vortx-ai/emem。从任何 MCP 客户端访问 ${SPACE_URL}/mcp 即可与之对话。

选项 C — 从源码构建

# 1) Build the workspace.
cargo build --release --workspace

# 2) Run the server (defaults: 0.0.0.0:5051, persistent storage at ./var/emem).
EMEM_BIND=0.0.0.0:5051 EMEM_DATA=./var/emem ./target/release/emem-server

# 3) Hit it.
curl -s http://localhost:5051/health
curl -s -X POST http://localhost:5051/v1/recall \
  -H 'content-type: application/json' \
  -d '{"cell":"damO.zb000.xUti.zde78"}'   # Mt Fuji

MCP / Claude Desktop / Cursor / Cline

可直接粘贴的配置位于 examples/ 下：

平台	文件
Claude Desktop	`examples/claude-desktop.json`
Claude Code	`examples/claude-code.mcp.json`
Cursor	`examples/cursor.mcp.json`
Cline (VS Code)	`examples/cline.mcp.json`
OpenAI GPT	`examples/openai-gpt-action.json`
LangChain	`examples/langchain.py`
LlamaIndex	`examples/llamaindex.py`

完整的智能体集成指南位于 docs/AGENTS.md。

实时端到端演示

两个 CLI 二进制文件针对正在运行的服务器执行完整协议，并将每一步的请求 + 响应 + 收据文件写入 var/demos/<UTC>/：

./target/release/emem-livedemo        # synthetic data, every primitive
./target/release/emem-realdemo        # real Copernicus DEM 30m S3 tiles

服务器在 GET /v1/demos 处公开跟踪工件。

工作原理

                ┌──────────────┐                  ┌────────────────────┐
   user ──────► │ AI agent     │ ──────► /v1/    │ emem responder     │
                │ (Claude /    │  /mcp           │  ┌──────────────┐  │
                │  Cursor /    │  /openapi.json  │  │ ed25519 key  │  │
                │  GPT / etc)  │                 │  └──────────────┘  │
                └──────┬───────┘                 │  ┌──────────────┐  │
                       │                         │  │ sled cache   │  │
                       │  signed receipt         │  └──────────────┘  │
                       ▼                         │  ┌──────────────┐  │
                ┌──────────────┐                 │  │ merkle log   │  │
                │ user reply   │                 │  └──────────────┘  │
                │ + cid        │                 │  ┌──────────────┐  │
                └──────────────┘                 │  │ vsicurl COG  │ ──► open data
                                                 │  └──────────────┘  │   (Cop-DEM, JRC,
                                                 └────────────────────┘    Hansen, ESA…)

地址代数（Token 成本）

字段	位数	线上传输格式	Token
`cell`	64	4 个 BPE 双字母组合	≤ 4
`tslot`	64	base32 短格式	≤ 2
`vec`	1792 D fp16	12 字节前缀	≤ 3
`cid`	32 B	8 字节前缀	≤ 3

加密：blake3 哈希、ed25519 签名、base32-nopad-lowercase CID。收据基于 blake3(request_id || served_at || primitive || cells || fact_cids) 进行签名，因此任何客户端都可以使用 /.well-known/emem.json 中的响应者公钥进行离线验证。

完整的数学原理 + 架构请参阅 docs/WHITEPAPER.md。线上传输格式规范请参阅 docs/SPEC.md。

开源，开放数据

emem 仅附带开源依赖项，并且在其默认构建中仅从开放数据提供商处读取数据。没有 API 密钥，没有运营商凭据，没有 SaaS 锁定。

关注点	处理方式
代码许可证	Apache-2.0 (本仓库)
Crate 许可证	所有依赖项均为 MIT / Apache-2.0 / BSD / ISC — 参见 NOTICE
数据许可证	Copernicus DEM (开放), JRC GSW (CC-BY 4.0), Hansen GFC (开放), ESA WorldCover (CC-BY 4.0), GHSL / WorldPop (CC-BY 4.0), OSM (ODbL) — 参见 NOTICE
身份验证	L0/L1 读取无需验证；L2 写入需要 ed25519 证明者密钥
传输	通过进程内 rustls + Let's Encrypt ACME 实现 HTTPS (无 Cloudflare，无代理)

工作区布局

emem/
├── Cargo.toml                # workspace root
├── crates/
│   ├── emem-core/            # types, manifests, errors
│   ├── emem-codec/           # cell64, cid64, vec64, hilbert
│   ├── emem-fact/            # canonical CBOR + facts + receipts
│   ├── emem-claim/           # structured claims, verify outcomes
│   ├── emem-cache/           # sled hot cache (cell64 → cid64 → fact)
│   ├── emem-fetch/           # vsicurl Range reads, source connectors
│   ├── emem-storage/         # Storage trait, append-only merkle log
│   ├── emem-cubes/           # 1792-D voxel cube loader (legacy AgriSynth bootstrap)
│   ├── emem-primitives/      # recall, compare, find_similar, …
│   ├── emem-attest/          # merkle root, batch verify
│   ├── emem-intent/          # intent → plan
│   ├── emem-mcp/             # MCP tool surface
│   ├── emem-api-rest/        # axum router + OpenAPI + content nego
│   └── emem-cli/             # emem-server, emem-livedemo, emem-realdemo
├── docs/                     # SPEC, WHITEPAPER, AGENTS, DEPLOY
├── examples/                 # paste-ready MCP configs
└── web/                      # landing surface (HTML, JSON, llms.txt)

部署

如需进行全面的多渠道发布（GitHub 公开、GHCR、Docker Hub 镜像、HuggingFace Space、MCP 服务器注册表、awesome-mcp-servers PR），请遵循 docs/GO_LIVE.md。

有关自托管裸机 emem.dev 风格实例的完整部署说明，请参阅 docs/DEPLOY.md。 emem.dev 的简要说明：

EMEM_TLS_DOMAINS=emem.dev,www.emem.dev EMEM_TLS_CONTACT=mailto:avijeet@vortx.ai ./target/release/emem-server
在云安全列表中打开 :443，
setcap 'cap_net_bind_service=+ep' ./target/release/emem-server，
将 emem.dev 的 A 记录指向主机的公网 IP — 完成。

服务器通过 rustls-acme / TLS-ALPN-01 自行处理 TLS + Let's Encrypt ACME（仅需 :443；无需 :80，无需 Cloudflare，无需 Caddy）。

贡献

欢迎提交 Issue 和 PR — 开发循环请参阅 CONTRIBUTING.md，漏洞披露请参阅 CODE_OF_CONDUCT.md 和 SECURITY.md。

许可证

Apache License 2.0 — 参见 LICENSE 和 NOTICE。

emem