Agents

Ela is memory for agents that already speak MCP or HTTP. A library (vault_id in the API) is what the token is bound to. Search returns structured handles with provenance. Coverage on every response says what was searched and what was left out.

How to connect

Path	Use when
Local MCP	The vault is on this machine. Stdio. Indexes `private/`. Read-only.
Cloud MCP	A remote agent. Streamable HTTP on the API host. Same read tools as local, plus `write_note` and `edit_note` with `notes.write` and connected write storage.
HTTP API	Filters, SDKs, and every write. Stable path `/v1`.
CLI `notes --remote`	A first-class client through `@elanotes/sdk`.

Tool arguments: MCP tools. Local MCP cannot write. Authenticated cloud MCP exposes write_note and edit_note only with notes.write and available write storage. Inspect tools/list before calling conditional tools; a valid read-only token can connect without them. Open local mode bypasses the permission check. Review stays on HTTP. Production origin: https://api.elanotes.com (/v1 and /mcp). Have the user create a personal access token in web Settings → Access tokens and provide it through ELA_API_TOKEN. Read is included; authenticated note mutations require notes.write. Supplying agent_id does not grant permission. Local clone: http://127.0.0.1:4000 — see MCP cloud and CLI.

curl -sS \
  -H "Authorization: Bearer $ELA_API_TOKEN" \
  "https://api.elanotes.com/v1/search?q=Paddle"

Procedure

Search: GET /v1/search?q= or MCP search_notes.
Read coverage (notes_searched, excluded_folders, layer_sequences) before using the hits. Zero hits with coverage is a valid answer.
Read a slice: GET /v1/notes/{slug}?start_line=&end_line= or read_note, using line_start / line_end and version_id from the hit.
Edit: POST /v1/notes/{note}:edit or cloud edit_note, with that version_id, old_string, new_string, agent_id, and an Idempotency-Key. Reuse a key only when the request body is identical.

Search response

q=Paddle on the sample vault returns the slug payments-provider-decision. The body is not in this payload. private/ is named in excluded_folders. content_hash is the full SHA-256 of the ranked chunk’s note version.

{
  "results": [
    {
      "score": 0.86,
      "provenance": {
        "slug": "payments-provider-decision",
        "version_id": "018f6a2c-1b4e-7a10-8c3d-5e6f708192a3",
        "content_hash": "c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00",
        "heading_path": ["Payments provider"],
        "line_start": 1,
        "line_end": 18,
        "observed_at": "2026-03-12T00:00:00.000Z",
        "indexed_at": "2026-09-07T12:00:00.000Z"
      }
    }
  ],
  "coverage": {
    "notes_searched": 42,
    "strong_match_count": 1,
    "excluded_folders": ["private/"],
    "layer_sequences": {
      "lexical": 120
    }
  },
  "ranker_version": "lexical-1",
  "index_version": 1,
  "next_page_token": null,
  "next_cursor": null
}

Retry when the version moved

A stale version_id is 409 VERSION_MOVED. That failure does not store the idempotency key. Follow hint:

GET /v1/notes/{note} to read the current version_id, then retry :edit with that version_id and a fresh Idempotency-Key.

{
  "error": "conflict",
  "reason": "VERSION_MOVED",
  "message": "version moved: current is 018f6a2c-1b4e-7a10-8c3d-5e6f708192a3 — re-read before editing",
  "hint": "GET /v1/notes/{note} to read the current version_id, then retry :edit with that version_id and a fresh Idempotency-Key.",
  "help": "https://docs.elanotes.com/api/errors#version_moved",
  "statusCode": 409,
  "requestId": "018f6a2e-6a7b-7f65-b182-a3b4c5d6e7f8",
  "details": []
}

Re-read the note, copy version_id, and submit the changed :edit with a new Idempotency-Key. Reuse a key only for an identical retry of a request that already returned a receipt. A different body for a key that already has a receipt is 409 IDEMPOTENCY_KEY_REUSED.

Receipts

A fresh vault queues agent writes. status: "queued" means the note has not changed. Record and report pending_id. In authenticated mode, GET /v1/writes/{id} requires notes.review: poll only with that permission. With a write-only token, hand the ID to a reviewer and report that receipt inspection requires review permission. Do not approve your own proposal or request additional review permission merely to finish the task. When auth is off, the permission check is skipped. The API accepts review-scoped personal tokens for :approve and :reject; human-controlled approval is the agent workflow rule, not a human-only credential restriction. Access tokens explains permissions and recovery from revoked or expired tokens. status: "applied" means the operation completed; unchanged: true means no new version was created. HTTP create/PATCH receipts include note in the GET shape without lines. Cloud MCP applied receipts include version and sequence fields without that embedded note; queued MCP receipts omit the HTTP slug. The JSON below illustrates HTTP receipts. Pass committed_seq as min_seq on the next search when you need to read your own write.

{
  "status": "queued",
  "pending_id": "018f6a2d-4e5f-7e54-a071-92a3b4c5d6e7",
  "slug": "hello"
}

{
  "status": "applied",
  "pending_id": "018f6a2d-2c3d-7d43-9f60-8192a3b4c5d6",
  "slug": "hello",
  "version_id": "018f6a2c-9c0d-7b21-9d4e-6f708192a3b4",
  "content_hash": "ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22",
  "committed_seq": 128,
  "unchanged": false,
  "note": {
    "slug": "hello",
    "note_id": "018f6a2b-0a1b-7c32-8e5f-708192a3b4c5",
    "version_id": "018f6a2c-9c0d-7b21-9d4e-6f708192a3b4",
    "content_hash": "ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22ab11cd22",
    "title": "Hello",
    "observed_at": null,
    "status": "active",
    "visibility": "default"
  }
}

What every retrieval keeps

Citations, not dumps. Hits are pointers. Fetch only what you need.
Coverage. Searched count, named exclusions, why the set is partial. Silent gaps are the failure mode Ela refuses.
Determinism. Same query, same index_version and ranker_version, same hits.
Vault isolation. Every query is scoped to one vault_id.
Zero is valid. Empty results plus coverage beat padded noise.
Cloud paths do not return private/ plaintext. Sync still stores ciphertext. Local MCP can read private/. See Privacy.

Machine-readable entry

This host serves /llms.txt, /llms-full.txt, and /skill.md. The wire contract is OpenAPI 3.1 (GET https://api.elanotes.com/openapi.json; this site’s copy is the API reference). Typed clients: TypeScript SDK and Python SDK. Workspace packages, not published.

Get started

Connect

Using Ela

API reference