emem — Protocolo de memoria terrestre para agentes de IA

Memoria de cada lugar de la Tierra, citable, direccionada por contenido y firmada. 1 protocolo. 8 primitivas de lectura. Recibos ed25519. Sin claves para L0/L1. Apache-2.0. Rust puro + solo datos abiertos.

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

Qué es

emem es un protocolo —no un servicio— para la memoria terrestre direccionada por contenido. Cada hecho sobre cada lugar obtiene un CID estable derivado del CBOR canónico de su carga útil (cell × band × tslot). Cada lectura es un recibo firmado que cualquier cliente puede verificar sin conexión con la clave pública ed25519 del respondedor.

emem está construido para agentes de IA: cuando un usuario menciona un lugar, el agente debe llamar a emem y citar receipt.fact_cids[0]. El protocolo funciona igual de bien sobre REST simple, MCP JSON-RPC 2.0 y acciones personalizadas de OpenAPI 3.1.

Por qué lo necesitan los agentes

Los LLM confabulan hechos espaciales. Sin una capa de memoria verificable y direccionada por contenido, cualquier respuesta a "¿qué hay en el lugar X?" es inauditable. emem soluciona esto:

• dando a cada hecho espacial un cid que dos partes vuelven a calcular byte a byte,

• firmando cada lectura con ed25519, incluyendo la clave pública del respondedor, para que el recibo sea verificable sin conexión,

• cubriendo toda la Tierra con una dirección cell64 cuadrada (~10 m × ~10 m en el ecuador, lat 21 bits × lng 22 bits — coincide con el paso nativo de Sentinel-1/-2). El alfabeto de bigramas del códec está ordenado por Hilbert para que las celdas vecinas obtengan cadenas visualmente similares, pero la geometría es una cuadrícula cuadrada.

Inicio rápido

Opción A — Docker (no se necesita cadena de herramientas Rust)

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

Opción B — HuggingFace Space

Una instancia alojada vive en huggingface.co/spaces/vortx-ai/emem. Acceda a ${SPACE_URL}/mcp desde cualquier cliente MCP para comunicarse con ella.

Opción C — Compilar desde el código fuente

# 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

Las configuraciones listas para copiar se encuentran en examples/:

El tutorial completo de integración de agentes está en docs/AGENTS.md.

Demos en vivo de extremo a extremo

Dos binarios CLI ejercitan el protocolo completo contra un servidor en ejecución y escriben archivos de solicitud + respuesta + recibo por paso en var/demos/<UTC>/:

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

El servidor expone los artefactos de seguimiento en GET /v1/demos.

Cómo funciona

                ┌──────────────┐                  ┌────────────────────┐
   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…)

Álgebra de direcciones (coste de tokens)

Criptografía: hashing blake3, firmas ed25519, CIDs base32-nopad-lowercase. Los recibos se firman sobre blake3(request_id || served_at || primitive || cells || fact_cids) para que cualquier cliente verifique sin conexión con la clave pública del respondedor en /.well-known/emem.json.

Matemáticas y arquitectura completas en docs/WHITEPAPER.md. Especificación del formato de cable en docs/SPEC.md.

Código abierto, datos abiertos

emem se distribuye solo con dependencias de código abierto y lee solo de proveedores de datos abiertos en su compilación predeterminada. Sin claves API, sin credenciales de operador, sin bloqueo de SaaS.

Diseño del espacio de trabajo

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)

Despliegue

Para un despliegue multicanal completo (GitHub público, GHCR, espejo de Docker Hub, HuggingFace Space, Registro de servidores MCP, PR de awesome-mcp-servers), siga docs/GO_LIVE.md.

Consulte docs/DEPLOY.md para conocer la historia completa de despliegue para una instancia autoalojada en metal desnudo al estilo emem.dev. TL;DR para emem.dev:

1. EMEM_TLS_DOMAINS=emem.dev,www.emem.dev EMEM_TLS_CONTACT=mailto:avijeet@vortx.ai ./target/release/emem-server

2. abra :443 en su lista de seguridad en la nube,

3. setcap 'cap_net_bind_service=+ep' ./target/release/emem-server,

4. apunte el registro A de emem.dev a la IP pública del host — listo.

El servidor realiza su propio TLS + Let's Encrypt ACME vía rustls-acme / TLS-ALPN-01 (solo se necesita :443; sin :80, sin Cloudflare, sin Caddy).

Contribución

Las incidencias y PR son bienvenidas — consulte CONTRIBUTING.md para el ciclo de desarrollo, CODE_OF_CONDUCT.md y SECURITY.md para la divulgación de vulnerabilidades.

Licencia

Licencia Apache 2.0 — consulte LICENSE y NOTICE.