Quickstart

Open In Colab Try this in Colab — 01_getting_started

How do I sign up and get an API key?

Sign up at areev.ai, create an organization, and generate an API key from the API Keys page (/keys in the Console).

When you create an organization, Areev provisions a dedicated cell for you at https://<org>.areev.ai. The cell exposes the REST API at /api, MCP at /mcp, A2A at /a2a, and gRPC on the same TLS endpoint — all enabled by default. API keys carry an ar_ prefix (admin-scoped) or ap_ prefix (project-scoped) and are shown exactly once at creation; copy yours into a secret store before leaving the page.

Set two environment variables for the SDK:

export AREEV_BASE_URL="https://acme.areev.ai"
export AREEV_API_KEY="ar_..."

How do I install the SDK?

Install the official Python, TypeScript, or Rust SDK from the standard package registry.

pip install areev
npm install @areev/sdk
cargo add areev

All three SDKs share the same surface: remember, recall, forget, add, get, supersede, health, stats, flush. The client reads AREEV_BASE_URL and AREEV_API_KEY from the environment, so credentials never end up in code.

How do I create a memory?

Memories are isolated context databases — each holds its own grains, indexes, policy, and audit trail. Create one with POST /api/memories and seal a compliance policy at creation time.

from areev import Areev

client = Areev()  # reads AREEV_BASE_URL + AREEV_API_KEY from env
client.create_memory(name="my-db", policy="gdpr")
POST /api/memories HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_...
Content-Type: application/json

{"name": "my-db", "policy": "gdpr"}

The policy (gdpr, ccpa, hipaa, lgpd, pipl, sox, eu_ai_act, ephemeral, default) determines which compliance checks run on every read and write. Each memory carries exactly one policy, sealed at creation time — pick the regulation that governs the workload stored in this memory.

How do I add a grain?

Add a Belief grain by providing subject, relation, and object fields. Areev serializes it to .mg format, encrypts it, indexes it, and appends an audit event.

mem = Areev(memory_id="my-db")
mem.add("belief", {"subject": "john", "relation": "likes", "object": "coffee"})
POST /api/memories/my-db/add HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_...
Content-Type: application/json

{"grain_type": "belief", "subject": "john", "relation": "likes", "object": "coffee"}

The add operation is atomic: Areev writes the encrypted .mg blob, updates the BM25 full-text index, updates the hexastore triple indexes, and logs an AuditEvent::GrainCreated — all in a single transaction. The response carries a 64-character SHA-256 hash that serves as the grain’s permanent address.

How do I recall grains?

Query by text, by structured fields, or both. Areev fuses BM25 full-text, HNSW vector similarity, and hexastore graph lookups into a single ranked list with Reciprocal Rank Fusion.

results = mem.recall(query="john preferences", limit=5)
for hit in results:
    print(hit.subject, hit.relation, hit.object, hit.score)
POST /api/memories/my-db/recall HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_...
Content-Type: application/json

{"query": "john preferences", "limit": 5}

Each result includes the grain’s content-address hash, decoded fields, grain type, relevance score, namespace, and creation timestamp. Post-retrieval filters for tags, importance, confidence, and contradiction detection run after fusion scoring.

  • SDKs: Python, TypeScript, and Rust client reference
  • Grain Types: All 10 grain types — Belief, Event, State, Workflow, Action, and more
  • HTTP / REST API: Complete HTTP endpoint reference
  • Authentication: API keys, scopes, and SSO