Quickstart

How do I install Areev?

Install the Python package with pip, or build the Docker image for a containerized deployment.

The areev Python package includes PyO3 bindings to the Rust engine, so you get native performance with a Python API. This is the fastest path to working with Areev as a context database for AI agents. For Rust-native builds with fine-grained feature control, use cargo install areev instead.

The Docker image bundles the dev build profile by default — FTS, HTTP, gRPC, MCP, A2A, app UI, document import, CAL, chat, hooks, vector search, auth, and rerank. Both approaches give you the same AI memory engine underneath.

pip install areev

# Build Docker image locally (no public registry)
docker build -f Dockerfile.dev -t areev:dev .

cargo install areev

How do I create a database?

Create a database directory with a compliance policy using areev create on the CLI or areev.create() in Python.

Areev stores all grains in a local directory. When you specify a policy like gdpr, the context database automatically enforces encryption-at-rest, consent tracking, 2-year TTL defaults, PII detection, and a hash-chained audit trail. The policy is sealed into the database at creation time and governs every subsequent operation.

You can combine multiple policies (e.g., gdpr + hipaa) for workloads that span regulatory jurisdictions. The 8 available presets are: gdpr, ccpa, hipaa, lgpd, pipl, sox, ephemeral, and permissive.

areev create --policy gdpr

import areev

db = areev.create("./areev-data", policies=["gdpr"])

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.

Belief grains are the most common AI agent memory type — they represent structured knowledge as semantic triples. The /add endpoint and db.add("belief", ...) method index all three fields in the hexastore, enabling graph traversal and triple-pattern queries. Areev computes a SHA-256 content hash that serves as the grain’s permanent address.

The add operation is atomic: Areev writes the encrypted .mg blob, updates the BM25 full-text index, inserts six hexastore permutation entries, and logs an AuditEvent::GrainCreated — all in a single Fjall batch.

db.add("belief", {"subject": "john", "relation": "likes", "object": "coffee"})

areev add belief subject=john relation=likes object="coffee"

POST /api/memories/default/add
Content-Type: application/json

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

How do I recall grains?

Query by text, by structured fields, or both. Areev automatically routes to the optimal search engine.

When you provide a query string, Areev runs BM25 full-text search via Tantivy. When you provide structural fields like subject or relation, it uses the hexastore for direct lookups. When you combine both, Areev fuses the results with Reciprocal Rank Fusion (RRF), producing a single ranked list. This autonomous memory retrieval adapts to whatever parameters you supply — no manual mode selection required.

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

results = db.recall(query="john preferences", limit=5)
for hit in results:
    print(hit["subject"], hit["relation"], hit["object"], hit["score"])

areev recall --query "john preferences" --limit 5 --json

POST /api/memories/default/recall
Content-Type: application/json

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

How do I start the server?

Start the HTTP server with areev serve. Add --mcp and --a2a to enable the Model Context Protocol and Agent-to-Agent protocol endpoints.

The server exposes 190+ HTTP endpoints at /api and optional gRPC, MCP, and A2A interfaces. Add --app app/dist/browser to serve the web console for visual grain exploration, compliance dashboards, and document import.

areev serve --http 0.0.0.0:4009 --mcp --a2a

Related

• Installation: All installation methods with build profiles
• Grain Types: All 10 grain types — Belief, Event, State, Workflow, Action, and more
• HTTP / REST API: Complete HTTP endpoint reference