Areev TypeScript SDK

TypeScript client library for the Areev knowledge database.

Installation

npm install @areev/sdk

Quick Start

import { Areev } from "@areev/sdk";

const areev = new Areev(); // reads AREEV_API_KEY, AREEV_URL from env

await areev.remember("John likes coffee");

const { results } = await areev.recall("what does John like?");
console.log(results);

Configuration

The client reads from environment variables by default:

| Variable | Default | Description | |----------|---------|-------------| | AREEV_API_KEY | — | API key (sent as Authorization: Bearer <key>) | | AREEV_URL | https://app.areev.ai | Server endpoint | | AREEV_MEMORY_ID | default | Memory database ID |

Or pass them explicitly:

const areev = new Areev({
  apiKey: "ar_...",
  url: "https://dub.areev.ai",
  memoryId: "my-memory",
});

API

| Method | Description | |--------|-------------| | remember(text) | Store natural-language memory (LLM extracts structure) | | recall(query) | Search memories | | forget(hash) | Delete a memory by hash | | add(grainType, fields) | Add a typed grain (low-level) | | get(hash) | Get a grain by hash | | supersede(oldHash, grainType, fields) | Update a grain | | chatInteractive(slug, message, { conversationId, executors }) | Harness chat with auto pause/resume for client:// tools | | harnessChat(slug, req) | Single harness turn (completed or requires_action) | | chatResume(slug, req) | Resume a paused session with client-side tool outputs | | cancelChatSession(slug, sessionId) | 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 control):

import { HttpClient } from "@areev/sdk";

const client = new HttpClient({
  url: "http://localhost:4009",
  memoryId: "default",
  apiKey: "your-key",
});

const { hash } = await client.add({
  grain_type: "belief",
  fields: { subject: "john", relation: "likes", object: "coffee" },
});

Harness Chat

Use chatInteractive 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:

import { Areev } from "@areev/sdk";
import type { ChatExecutors } from "@areev/sdk";

const areev = new Areev();

const executors: ChatExecutors = new Map();
executors.set("get_weather", async (_name, args) => {
  const { city = "unknown" } = (args as { city?: string }) ?? {};
  return { city, temp_c: 22, conditions: "sunny" };
});

const response = await areev.chatInteractive(
  "weather-harness",
  "What's the weather in Paris?",
  { conversationId: "conv-1", executors },
);
console.log(response.text);

harnessChat, chatResume, and cancelChatSession are the low-level primitives if you want to run the loop yourself.

Transports

| Transport | Status | |-----------|--------| | HTTP/REST | Available | | MCP | Planned | | A2A | Planned |

Generated Types

Full OpenAPI types are generated from the Areev spec:

npm run codegen

License

BUSL-1.1