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은 서비스가 아닌 프로토콜로, 콘텐츠 주소 지정이 가능한 지구 메모리를 위한 것입니다. 모든 장소에 대한 모든 사실은 해당 (cell × band × tslot) 페이로드의 표준 CBOR에서 파생된 안정적인 CID를 가집니다. 모든 읽기는 응답자의 ed25519 공개 키를 사용하여 모든 클라이언트가 오프라인에서 확인할 수 있는 서명된 영수증입니다.

emem은 AI 에이전트를 위해 구축되었습니다. 사용자가 장소를 언급하면 에이전트는 emem을 호출하고 receipt.fact_cids[0]를 인용해야 합니다. 이 프로토콜은 일반 REST, MCP JSON-RPC 2.0 및 OpenAPI 3.1 사용자 지정 작업에서 동일하게 잘 작동합니다.

에이전트에게 필요한 이유

LLM은 공간적 사실을 꾸며냅니다(confabulate). 검증 가능하고 콘텐츠 주소 지정이 가능한 메모리 계층 없이는 "장소 X에 무엇이 있는가?"라는 모든 답변을 감사할 수 없습니다. emem은 다음을 통해 이를 해결합니다:

두 당사자가 바이트 단위로 다시 계산할 수 있는 cid를 모든 공간적 사실에 부여,
응답자의 공개 키를 포함하여 ed25519로 모든 읽기에 서명함으로써 영수증을 오프라인에서 검증 가능하게 함,
정사각형 cell64 주소로 지구 전체를 커버(적도에서 약 10m × 10m, 위도 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…)

주소 대수 (토큰 비용)

필드	비트	와이어 형식	토큰
`cell`	64	4 BPE 바이그램	≤ 4
`tslot`	64	base32 short	≤ 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 (본 저장소)
크레이트 라이선스	모든 종속성은 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 없음).

기여

이슈와 PR을 환영합니다 — 개발 루프는 CONTRIBUTING.md를, CODE_OF_CONDUCT.md를, 취약점 공개는 SECURITY.md를 참조하세요.

라이선스

Apache License 2.0 — LICENSE 및 NOTICE를 참조하세요.

emem