emem

<div align="center">

<img src="web/logo-300w.png" alt="emem logo" width="72">

<h1>Encode where the data lives. Decode with any AI.</h1>

<p><b>emem is shared, verifiable memory for machines and AI. The proof travels; the files stay where they are.</b></p>

<p><a href="https://emem.dev">Try it, no key</a> · <a href="#quickstart">Quickstart</a> · <a href="#memory-that-changes-without-losing-its-history">A worked example</a> · <a href="https://emem.dev/verify">Verify a token</a> · <a href="https://emem.dev/agents.md">Agent guide</a> · <a href="https://emem.dev/docs/">Docs</a></p>

[![ci](https://github.com/Vortx-AI/emem/actions/workflows/ci.yml/badge.svg)](https://github.com/Vortx-AI/emem/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/ememdev?label=pypi%20ememdev)](https://pypi.org/project/ememdev/)
[![npm](https://img.shields.io/npm/v/@vortxai/emem?label=npm%20%40vortxai%2Femem)](https://www.npmjs.com/package/@vortxai/emem)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
[![Whitepaper DOI](https://img.shields.io/badge/whitepaper-10.5281%2Fzenodo.20706893-3b5)](https://doi.org/10.5281/zenodo.20706893)

[![ChatGPT](https://img.shields.io/badge/ChatGPT-emem-10a37f?logo=openai&logoColor=white)](https://chatgpt.com/plugins/plugin_asdk_app_6a6a0832a59081918b19aec0ddf9ec77)
[![Claude plugin](https://img.shields.io/badge/Claude-plugin-D97757)](plugins/emem/)
[![GitHub MCP Registry](https://img.shields.io/badge/GitHub%20MCP%20Registry-io.github.Vortx--AI%2Femem-181717?logo=github&logoColor=white)](https://github.com/mcp/Vortx-AI/emem)
[![Install in VS Code](https://img.shields.io/badge/VS%20Code-Install%20emem-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=emem&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Femem.dev%2Fmcp%22%7D)
[![Dify](https://img.shields.io/badge/Dify-emem-1C64F2)](https://marketplace.dify.ai/plugin/vortx-ai/emem)

</div>

<p align="center"><img src="docs/media/readme/20-encode-decode.webp" alt="Three panels. Your data: files, machines and archives, with source files kept local. Each sends a signed record into shared memory, where records link by identity, history and derivations. Any AI, whether Claude, ChatGPT or your own agent, resolves the same record and verifies it. Caption: one reference, the same record, checked independently." width="880"></p>

## Trust without moving the file

Today, to trust a piece of data you usually have to hold it. A satellite downlinks the whole capture, a lab emails the spreadsheet, a company uploads its documents to whichever AI is reading them, and every copy is one more place the data can leak or quietly change.

emem splits the job in two.

- **Encoding happens at the source, and stays private.** A file server, a lab, a camera or a payload computer hashes what it holds into units and signs a small record under its own key. The bytes do not have to leave. What leaves is a commitment to them: a content id, a Merkle root, a signature.
- **emem is the decoding half.** Any model, in Claude, in ChatGPT or in your own code, resolves a short token back to that exact record, checks who signed it, and proves that one unit belongs to the whole, without trusting the sender, and without trusting emem.

A token lets a reader resolve the published record and check content they are given against it. It does not reveal what you kept: a tree token over a private file exposes the units you chose to publish and nothing else.

## What crosses, and what stays

| Source | Where it is encoded | What crosses | What stays | Status |
|---|---|---|---|---|
| **Documents, datasets, model weights, code** | the tokeniser on [emem.dev](https://emem.dev) (in your browser: code by definition, safetensors by tensor, zip and pptx by entry, PDF by page) or [`tree_proof.py`](plugins/emem/skills/emem-tokenise-files/) on your machine | one `emem:tree:` token: each unit's BLAKE3 folded into a Merkle root, in an index you sign | every unit you do not choose to publish | shipped |
| **Your own algorithm** | wherever you run it | `emem_derive`: your value, the signed facts it read, and an optional `code_cid`, the hash of your code, all signed by your key | the code. emem never runs it; it pins it by hash | shipped; emem re-runs only pure operations (`delta`, `mean`, `sum`) |
| **A payload on a satellite, drone, camera or robot** | [`emem-airgap`](crates/emem-airgap/README.md) on the device, with no network; the `emem-encode` sidecar adds an execution trace | a signed custody record: these bytes, this name, this size, at this time, under this key | the payload | the encoders ship (arm64 and amd64); the public device gate admits no real hardware yet |
| **Open Earth archives** | emem's own readers of registered archives | signed facts, each naming its source bytes | nothing private: the archives are public, so anyone can recompute | shipped, the first corpus |

What each check proves is stated with it. A custody record says bytes arrived, not that the sensor was calibrated. A tree proves a unit was in the file you signed, not that the file is true. A `code_cid` says which code you claim produced a value; running arbitrary private code in a sandbox is not built.

## Quickstart

No account and no API key to read.

**1. Connect an MCP host** (Claude Code here; [every other host](https://emem.dev/reference#client-setup)):

```bash
claude mcp add --transport http emem https://emem.dev/mcp
```

**2. Prove one part of a file without the rest of it.** This repository's `LICENSE` is published as a signed tree of six 2 KB units, so you can try the file path with nothing to set up. From a clone:

```bash
curl -s "https://emem.dev/memories/by_attester/k572x7go/readme-example/license-tree.md" > index.md
curl -s "https://emem.dev/v1/tree/xrnco3igl6j2j4kehg4z33ggk4?row=3" > row.json
python3 plugins/emem/skills/emem-tokenise-files/scripts/tree_proof.py check row.json index.md LICENSE
```

The index names every unit's hash and the root; the row carries unit 3 and its audit path. The check confirms bytes 6144 to 8191 are in the file the key `k572x7go` signed, by hashing those bytes and walking three steps to the root. For your own file, `tree_proof.py build report.md` cuts it into units and prints the index offline; sign and publish it under your own key ([the skill](plugins/emem/skills/emem-tokenise-files/SKILL.md) walks through it). The file never leaves your machine.

**3. Read a signed measurement and check it offline** (curl, jq, Python):

```bash
curl -fsS https://emem.dev/v1/recall -H 'content-type: application/json' \
  -d '{"place":"Cairo","bands":["copdem30m.elevation_mean"]}' > fact.json
jq '.facts[0] | {cell, value, unit, memory_token}' fact.json

jq '{token: .facts[0].memory_token}' fact.json \
  | curl -fsS https://emem.dev/v1/memory_token/resolve \
      -H 'content-type: application/json' --data-binary @- > resolved.json
```

```python
# pip install "ememdev[signing]"
import json
from ememdev.verify import verify_receipt_offline

verdict = verify_receipt_offline(json.load(open("resolved.json"))["receipt"])
print(verdict.ok, verdict.why)   # True, checked in this process with no network call
```

The check uses the public key the receipt carries. To know it was emem that signed, pin emem's key from [`/.well-known/emem.json`](https://emem.dev/.well-known/emem.json), or check the token at [emem.dev/verify](https://emem.dev/verify).

<details>
<summary>Or just ask, from the shell, Python or TypeScript</summary>

```bash
curl -s -X POST https://emem.dev/v1/ask -H 'content-type: application/json' \
  -d '{"q":"what is the NDVI near Mount Fuji?"}' | jq '{answer, receipt: .receipt.fact_cids}'
```

```python
# pip install "ememdev[signing]"
from ememdev import Client
from ememdev.verify import verify_receipt_offline

with Client() as em:
    out = em.ask("what is the NDVI near Mount Fuji?")
    print(out["answer"], verify_receipt_offline(out["receipt"]).ok)
```

```ts
// npm i @vortxai/emem
import { Client } from "@vortxai/emem";

const out = await new Client().ask({ q: "what is the NDVI near Mount Fuji?" });
console.log(out.answer, out.receipt.fact_cids);
```

There is no rule for turning a tool name into a REST path, so do not guess one: `emem_memory_search` answers at `POST /v1/memory/search` and `emem_verify_receipt` at `POST /v1/verify_receipt`. The authority is [`/openapi.json`](https://emem.dev/openapi.json); over MCP, call the tool by name.

</details>

**For agents.** Connect to `https://emem.dev/mcp`. It advertises the 18 tools of the core loop in one page, about 75 KB of context, not the whole catalog: loading all 115 descriptors costs about 324 KB. For the lightest first contact, `emem_tools` returns the loop and a menu in about 13 KB, and `tools/call` dispatches every tool by name, with or without its `emem_` prefix. To hand records on, prefer a bundle: `emem_memory_bundle` names up to 256 facts in 38 characters.

## Memory that changes without losing its history

One field, worked end to end on the live node on 2026-10-10. Every token below resolves, and you can check each step yourself.

**1. Name the thing once.** The field gets an identity that stays put while everything measured about it changes:

```text
emem:entity:2kmmk5bflnt5v2g7fh5y5ezqhe     "Wheat field west of Ludhiana", a farm_plot at cell defi.zb560.kUtU.sozo
```

**2. Two observations, each its own record.** NDVI read from Sentinel-2 on two dates. Each reading has its own content id, so a later reading never overwrites an earlier one:

```text
2026-03-12   NDVI 0.893   emem:fact:defi.zb560.kUtU.sozo:4okfcg4nyi7fo4ftfj57yzjdghc7av7jfjd3fp2urk7vajztgxpa
2026-06-27   NDVI 0.158   emem:fact:defi.zb560.kUtU.sozo:hbliam74soj7pmqy7ig67hyyqn7lz6fe7baagv743fzi75p2drpq
```

**3. A result derived from them, and recomputed.** An agent registers the drop, signed with its own key, naming both readings as inputs and p