# ChainMemory API

> REST API for persistent, verifiable AI memory. Memories are encrypted and anchored individually on ChainMemory's public chain (Chain ID 202604) and distilled into a versioned Project Brain. The complete machine-readable contract is the OpenAPI 3.1 document below; this file is the short orientation.

Last updated: 2026-09-28.

- OpenAPI 3.1: https://api.chainmemory.ai/openapi.json
- Documentation: https://docs.chainmemory.ai
- MCP server wrapping this API: `npx -y chainmemory-mcp` (MCP Registry: `io.github.chaelynet/chainmemory`)

## Authentication

Send the API key in the `x-api-key` header:

```
x-api-key: aic_<48 hex chars>
```

Get a key and AIC credit for fees, free, at https://faucet.chainmemory.ai. POST /v1/keys also creates one, limited to 3 new keys per IP and 100 in total every 24 hours. Endpoints marked public below need no key.

## Memories

- [POST /v1/memory](https://api.chainmemory.ai/openapi.json): Write a memory. Fee 0.001 AIC. `event_hash` is assigned when the memory syncs to the chain, about 30 seconds later.
- [POST /v1/memory/sealed](https://api.chainmemory.ai/openapi.json): Blind vault. Store a memory the client already encrypted; the server cannot read it. Send its search vector (`embedding`, 384 numbers computed on the client) to make it searchable.
- [GET /v1/memory/{id}/blob](https://api.chainmemory.ai/openapi.json): Fetch a sealed memory's ciphertext to decrypt on the client.
- [GET /v1/memories/list](https://api.chainmemory.ai/openapi.json): List memories, filterable by project.
- [GET /v1/memories/search](https://api.chainmemory.ai/openapi.json): Semantic search by query text. `POST /v1/memories/search` with a `query_embedding` searches by vector instead, so the query text never reaches the server. Sealed memories appear only if their vector was sent when they were stored, and always without text; a vector search also returns their ciphertext for the client to decrypt.
- [GET /v1/memory/context](https://api.chainmemory.ai/v1/memory/context): Recent memories formatted for an LLM. `limit` default 10, max 50.
- [GET /v1/memory/context/expanded](https://api.chainmemory.ai/v1/memory/context/expanded): Same, `limit` default 50, max 200.
- [POST /v1/memories/{id}/trust](https://api.chainmemory.ai/v1/memories/:id/trust): Owner governance of trust (approve/quarantine). Quarantined memories are excluded from agent-facing outputs.
- [GET /v1/memory/{id}/forensics](https://api.chainmemory.ai/v1/memory/:id/forensics): Verifiable timeline of a memory: birth, trust, reads, injections, anchoring.

## Project Brain

- [GET /v1/project/{name}/state](https://api.chainmemory.ai/openapi.json): Consolidated, versioned project state with `state_hash`.
- [POST /v1/project/{name}/state/ops](https://api.chainmemory.ai/openapi.json): Consolidate with operations. Fee 0.05 + 0.005 per op. Evidence must cite memories the server can resolve, otherwise HTTP 422 `evidence_unresolved`.
- [POST /v1/project/{name}/state/rollback](https://api.chainmemory.ai/v1/project/:name/state/rollback): Append-only restore to a prior anchored version.
- Role contracts and sessions: `GET /v1/project/{name}/roles`, `POST /v1/project/{name}/role/{roleId}/assume` (fee 0.001), `POST /v1/session/{id}/release`.

## Context injection

- [POST /v1/inject](https://api.chainmemory.ai/openapi.json): Load chosen memories into a conversation as a citable block. Fee 0.1 AIC.
- `GET /v1/inject/balance`, `GET /v1/inject/status/{id}`, `GET /v1/inject/history`.

## Verification

Each memory is anchored individually in the memory contract `0xE84224e2660fd620aA6d09522718Ae0e5cF33F7d`.

- [GET /v1/my/memory/{memory_number}/proof](https://api.chainmemory.ai/openapi.json): Owner gets `chain_memory_id`, `event_hash` and `chain_tx` to share.
- [GET /v1/memory/{chain_memory_id}/verify](https://api.chainmemory.ai/openapi.json): Public. The on-chain record: event hash and metadata. The ciphertext is not returned here; it stays on-chain, readable with getMemory() but not decryptable without the key.
- [GET /v1/verify/{project}](https://api.chainmemory.ai/openapi.json): Public. Every anchored Project Brain version and its coordinates in ProjectStateAnchor `0xa7A8BA51950255b3e223a6745597C67009Fe7875`.
- [POST /v1/verify-memory](https://api.chainmemory.ai/openapi.json): Public, POST only. Merkle inclusion proof. Only memories grouped by `POST /v1/compress` have one; the rest return `anchor_status: "uncompressed"`, which does not mean unanchored.

Independent check without the API: call `getMemory(chain_memory_id)` on the memory contract through https://rpc.chainmemory.ai.

## Errors

Responses are JSON, including errors, which carry an `error` field and a meaningful HTTP status: 400 invalid input, 402 `insufficient_aic`, 404 not found, 409 version conflict, 422 unresolved evidence.

## Links

- Website and explorer: https://chainmemory.ai
- Live network stats: https://api.chainmemory.ai/v1/stats
- JSON-RPC: https://rpc.chainmemory.ai
- npm: https://www.npmjs.com/package/chainmemory-mcp
- GitHub: https://github.com/chaelynet