areev 0.1.2

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
chat_interactive(slug, message, executors, ...)	Harness chat with auto pause/resume for client:// tools
harness_chat(slug, req)	Single harness turn (completed or requires_action)
chat_resume(slug, req)	Resume a paused session with client-side tool outputs
cancel_chat_session(slug, session_id)	Cancel a paused session (idempotent)
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"},
    ))

Harness Chat

Use chat_interactive to drive a harness (Areev's LLM-plus-tools runtime) with client-side tool executors. The helper runs the pause/resume loop for you when the model calls a client:// tool:

from areev import Areev

areev = Areev()

def get_weather(_name, args):
    city = args.get("city", "unknown")
    return {"city": city, "temp_c": 22, "conditions": "sunny"}

response = areev.chat_interactive(
    "weather-harness",
    "What's the weather in Paris?",
    executors={"get_weather": get_weather},
    conversation_id="conv-1",
)
print(response.text)

AsyncAreev exposes the same method as a coroutine. harness_chat, chat_resume, and cancel_chat_session are the low-level primitives if you want to run the loop yourself.

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