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. The server 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).

import areev

db = areev.open("./my-memory", policies=["gdpr"])
POST /api/memories
Content-Type: application/json

{
  "name": "Customer Support",
  "description": "Memory for support agent conversations"
}
areev create --policy 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.

count = db.count()
space = db.disk_space()
GET /api/memories
GET /api/memories/customer-support/stats
areev info

How do I configure policies on a memory?

Areev supports 8 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, ephemeral, and permissive. Each preset configures encryption requirements, consent tracking, retention periods, PII detection, and audit trail behavior. You can apply multiple presets simultaneously — for example, gdpr,hipaa enforces the union of both rule sets.

To modify an existing memory’s policies, use PUT /api/memories/{id}/policy with add_policies and remove_policies arrays. 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
Content-Type: application/json

{
  "add_policies": ["hipaa"],
  "remove_policies": [],
  "downgrade_reason": "adding HIPAA compliance"
}
GET /api/memories/customer-support/policy
areev create --policy gdpr,hipaa
areev modify --add-policy hipaa
areev modify --remove-policy ccpa --reason "switching to GDPR"

How do I delete a memory?

Delete a memory with DELETE /api/memories/{id}. This unregisters the memory from the server but does not remove data from disk.

The API-level delete is a soft operation that removes the memory from the registry, making it inaccessible through all endpoints. The underlying Fjall LSM data files remain on disk until you run the CLI destroy command. This two-step design prevents accidental data loss — an API call alone cannot permanently destroy stored grains.

For complete data destruction, use areev destroy --confirm from the CLI. This permanently removes all data files from disk, and the operation is irreversible.

DELETE /api/memories/customer-support
areev destroy --confirm