areev 0.0.0

Python SDK for the Areev knowledge database — HTTP, gRPC, and MCP transports

Areev Python SDK

Python client library for the Areev knowledge database.

Installation

pip install areev

For gRPC transport:

pip install areev[grpc]

Quick Start

from areev import Areev

areev = Areev()  # reads AREEV_API_KEY, AREEV_URL from env
areev.remember("John likes coffee")

results = areev.recall("what does John like?")
for hit in results.results:
    print(f"  {hit.grain_type}: {hit.fields}")

Configuration

The client reads from environment variables by default:

Variable	Default	Description
AREEV_API_KEY	—	API key (sent as X-API-Key header)
AREEV_URL	https://app.areev.ai	Server endpoint
AREEV_MEMORY_ID	default	Memory database ID

Or pass them explicitly:

areev = Areev(api_key="ar_...", url="https://dub.areev.ai", memory_id="my-memory")

Async

from areev import AsyncAreev

async with AsyncAreev() as areev:
    await areev.remember("John likes coffee")
    results = await areev.recall("what does John like?")

API

Method	Description
remember(text)	Store natural-language memory (LLM extracts structure)
recall(query)	Search memories
forget(hash)	Delete a memory by hash
add(grain_type, **fields)	Add a typed grain (low-level)
get(hash)	Get a grain by hash
supersede(old_hash, grain_type, **fields)	Update a grain
health()	Health check
stats()	Database statistics
flush()	Flush write buffer

Low-Level Client

For advanced use cases (custom request objects, full async control):

from areev import HttpClient, AreevConfig, AddRequest, GrainType

config = AreevConfig(url="http://localhost:4009", memory_id="default", api_key="your-key")
async with HttpClient(config) as client:
    resp = await client.add(AddRequest(
        grain_type=GrainType.BELIEF,
        fields={"subject": "john", "relation": "likes", "object": "coffee"},
    ))

Transports

Transport	Extra	Status
HTTP/REST	(default)	Available
gRPC	areev[grpc]	Available
MCP	—	Planned

Code Generation

Generate gRPC stubs and Pydantic models from the Areev spec:

pip install areev[dev]
./scripts/generate.sh

License

BUSL-1.1