Managing Memories

What is a memory instance?

A memory instance is an isolated context database that holds grains, indexes, policies, and an audit trail. Each instance operates independently, so data stored in one memory never leaks into another.

Areev treats every memory as a self-contained AI memory store backed by Fjall LSM for persistence, Tantivy BM25 for full-text search, and HNSW for vector similarity. When you create a memory, Areev provisions all three index layers and initializes the audit log. Each cell supports up to 1,000 concurrent memory instances, each identified by a slug ID derived from its name. If a slug collision occurs, Areev appends a short UUID suffix to guarantee uniqueness.

You can also configure optional parameters at creation time: vector_backend (usearch or faiss), dedup policy (none, exact, fuzzy, upsert), dedup_threshold for fuzzy dedup similarity, guardrail_patterns for content blocking, and guardrail_mode (exact, contains, fuzzy).

from areev import Areev

client = Areev()
client.create_memory(
    id="customer-support",
    name="Customer Support",
    description="Memory for support agent conversations",
    policies=["gdpr"],
)
POST /api/memories HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_...
Content-Type: application/json

{
  "id": "customer-support",
  "name": "Customer Support",
  "description": "Memory for support agent conversations",
  "policies": ["gdpr"]
}

How do I list and inspect memories?

List all memories with GET /api/memories and inspect a single memory with GET /api/memories/{id}.

The list response returns each memory’s id, name, description, and created_at timestamp. For detailed statistics, call GET /api/memories/{id}/stats to retrieve grain counts by type, disk usage, active namespaces, and encryption status. This is the fastest way to audit what an autonomous memory store contains without querying individual grains.

The stats response includes total_grains, type_counts (breakdown by grain type), namespaces (all namespaces in use), disk_space_bytes, has_encryption, and has_policy.

mem = client.memory("customer-support")
stats = mem.stats()
print(stats.total_grains, stats.disk_space_bytes)
GET /api/memories/customer-support/stats HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_...

How do I configure policies on a memory?

Areev supports 9 compliance policy presets that you can seal at creation time or modify later via the API.

Available presets are gdpr, ccpa, hipaa, lgpd, pipl, sox, eu_ai_act, ephemeral, and default. Each preset configures encryption requirements, consent tracking, retention periods, PII detection, and audit trail behavior.

At creation time each memory carries exactly one policy — pass it as the policy field on POST /api/memories. To stack additional presets later, use PUT /api/memories/{id}/policy with add_policies and remove_policies arrays; once multiple policies are active they apply as a union (e.g. gdpr + hipaa enforces both rule sets). Every policy change is logged in the audit trail with the provided downgrade_reason field, creating a compliance-grade record of when and why policies changed.

PUT /api/memories/customer-support/policy HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_...
Content-Type: application/json

{
  "add_policies": ["hipaa"],
  "remove_policies": [],
  "downgrade_reason": "adding HIPAA compliance"
}

How do I delete a memory?

Delete a memory with DELETE /api/memories/{id}. This permanently removes the memory and all its grains from your cell — the operation is irreversible and produces a MemoryDestroyed audit event before deletion.

DELETE /api/memories/customer-support HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_...