2-minute quickstart

Prerequisites: Docker and uv installed. That’s it — the defaults in .env.example are enough, no LLM key required to try it out.

1. Infrastructure

PostgreSQL 16 + pgvector, Redis 7

docker compose up -d

docker-compose.yml starts pgvector/pgvector:pg16 (user haki, database haki, exposed on host port 5433 — not 5432, already taken by a local Windows Postgres on many machines) and redis:7 (provisioned, intended for the queue).

Python dependencies

uv sync

uv installs Python 3.12 itself if needed, plus haki (the Python SDK, a local editable dependency declared in pyproject.toml).

Migrations

uv run alembic upgrade head

Applies the 8 migrations (alembic/versions/0001 through 0008): the pgvector extension, Ledger tables, full-text search columns, forget_receipts, auth/RLS/feedback, episodic events, organizations.

The API

uv run uvicorn app.main:app --port 8100

Something not working? bash scripts/doctor.sh diagnoses Docker, the containers, Postgres, .env, migrations and the API in one command — read-only, no side effects, safe to rerun as often as needed.

2. Proof that it works

In a second terminal:

uv run haki connect --api-url http://localhost:8100
uv run haki verify

haki connect tests /health and writes ~/.haki/config.json. haki verify runs the full scenario in a few seconds: it memorizes a preference, opens a new conversation (new thread_id), and checks that the agent remembers it — with the latency of every step.

haki verify — subject usr_verify_8a4a67338864
  [  0.05 s] capture (thread thr_a1e14345)
  [  3.25 s] consolidate: 1 job(s) processed
  [  0.04 s] context (new thread thr_ef814359)
  recalled: invoice_language = {"language": "fr"}
  trace_id: 0587fc4f-74a1-46af-a592-5789d1269072
OK — total 3.35 s

If no API key is configured, haki verify attempts a key bootstrap for the prj_haki_verify project (works on a fresh server without HAKI_ADMIN_KEY, or in dev-open mode); on a server that refuses that bootstrap, the scenario fails with a clear message instead of a silent error.

Multilingual by default: Haki understands and memorizes in French, English, Spanish and ~50 other languages (local multilingual embeddings, paraphrase-multilingual-MiniLM-L12-v2). A memory captured in English is recalled by a question in French — verified by scripts/check_multilingual.py (3/3 PASS on the last documented run in docs/SECURITY.md).

3. First manual call: capture then context

First, create a key (the very first creation is free as long as no key exists yet — see API keys):

curl -X POST http://localhost:8100/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"org_id": "org_acme", "project_id": "prj_support", "label": "dev"}'

The response contains key (hk_...) only once — copy it. Add -H "Authorization: Bearer hk_..." to every call below.

Capture a preference

curl -X POST http://localhost:8100/v1/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hk_..." \
  -d '{
    "idempotency_key": "demo-1",
    "events": [{
      "org_id": "org_acme", "project_id": "prj_support",
      "subject_type": "user", "subject_id": "usr_42",
      "kind": "conversation.message",
      "occurred_at": "2026-08-01T10:00:00Z",
      "payload": {"role": "user", "content": "I prefer my invoices in French."},
      "classification": ["customer-data"]
    }]
  }'

Consolidate (dev/ops — extracting the durable fact)

curl -X POST http://localhost:8100/v1/consolidate \
  -H "Authorization: Bearer hk_..."

In development (HAKI_LLM_PROVIDER=fake, the default), extraction makes no network call. In production (HAKI_LLM_PROVIDER=openai), this same call triggers a real LLM extraction.

Ask for memory before an answer

curl -X POST http://localhost:8100/v1/context \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hk_..." \
  -d '{
    "project_id": "prj_support", "subject_id": "usr_42",
    "query": "what language should the invoice be sent in?",
    "budget_tokens": 900
  }'

The response contains the fact invoice_language: {"language": "fr"}, its validity date, the id of the source event, and a trace_id inspectable via GET /v1/inspect/{trace_id}.

What’s next

Concepts

Understand the Ledger, bitemporality, supersession and the Context Assembler before you integrate.

Python SDK

HakiClient, build_prompt_context, capture_turn, the haki CLI.

Cursor

One-click MCP server, or Cursor Hooks for guaranteed capture.

OpenAI gateway

Automatic memory by changing only base_url.

Welcome

Concepts

SDKs

Integrations

Operations

2-minute quickstart

1. Infrastructure

2. Proof that it works

3. First manual call: capture then context

What’s next

Concepts

Python SDK

Cursor

OpenAI gateway

​1. Infrastructure

​2. Proof that it works

​3. First manual call: capture then context

​What’s next

Concepts

Python SDK

Cursor

OpenAI gateway

1. Infrastructure

2. Proof that it works

3. First manual call: capture then context

What’s next