Haki

Haki

Reliable memory for AI agents

*Context with proof: every fact carries a date, a source, and a status.*

Haki gives any AI agent a memory that lasts for months — that tells current from stale — and that can prove every recollection.

Quickstart · Coded agent · Cursor · n8n · Gateway · API · gethaki.space

---

What Haki does

Today, an AI agent remembers nothing beyond a single conversation: every new session starts from scratch, re-explains context, and can apply a preference that went stale months ago with no way to tell.

Haki is an open-source (Apache-2.0), persistent memory layer, independent of whatever model or framework you use: it extracts structured facts from an agent's exchanges, keeps them current over time, and hands every new request a relevant, dated, sourced context packet. It stays entirely under your control — one docker compose up installs it, and your existing agent, model, and infrastructure don't change.

---

The problem

Teams building AI agents in production run into the same limits, every time:

Existing approaches (generic vector stores, conversation summaries) work in a demo but degrade after a few weeks of real usage: stale information served as current, undetected contradictions, zero explainability.

---

The approach

A fact ledger, not a conversation history. Haki doesn't archive raw messages to replay later: it extracts structured facts from them — preferences, constraints, decisions — each one linked back to the source event that grounds it.

Bitemporality and supersession. Every fact carries an explicit validity date and status. When information changes, the old fact is marked *superseded* — never silently deleted, never served again as current. On an unresolved contradiction, both versions are held back and flagged rather than served at random.

Systematic traceability. Every context packet injected comes with its sources, its validity dates, and a trace explaining which memories were kept, excluded, or blocked, and why. "Why did the agent use this piece of information?" has a verifiable answer in under a minute.

---

Quickstart

Prerequisites: Docker and uv. The defaults in

.env.example are enough to get started — no key required. For custom

configuration (a real LLM key, etc.), copy that file to .env.

# Infrastructure (PostgreSQL 16 + pgvector, Redis 7)

docker compose up -d

Dependencies (uv installs Python 3.12 if needed)

uv sync

Database

uv run alembic upgrade head

API

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

If anything goes wrong, bash scripts/doctor.sh diagnoses Docker, the

containers, Postgres, .env, migrations, and the API in one command — read

only, no side effects, safe to re-run as often as needed.

In a second terminal, verify everything works:

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

uv run haki verify

haki verify runs a complete scenario in a few seconds: a preference, then a change of mind in the same conversation, then a new conversation that queries memory. It must serve the current value, keep the old one at status superseded instead of erasing it, and tie the whole thing to a trace.

haki verify — subject usr_verify_91d952a5e06f

✔ capture "Je préfère recevoir mes factures en français." thr_35bb7ecf ✔ consolidate 1 fact(s) extracted 0.2s ✔ capture "En fait, envoie-les moi en anglais plutôt, pa..." thr_35bb7ecf (same thread) ✔ consolidate 1 supersession 0.1s ✔ context NEW thread thr_3a21ef34 0.0s

recalled invoice_language = {"language": "en"} valid since 2026-08-11 hidden invoice_language = {"language": "fr"} superseded trace 7c99a8de-4905-43b4-94df-21fb66492b3b

OK — your agent remembered across conversations, and it can prove it. 0.5s

The command exits 1 if the stale value is still served, or if the old value isn't found marked as superseded: serving the right value by accident, with no link between the two facts, isn't a memory that actually updates.

Multilingual by default: local embeddings are multilingual (French,

English, Spanish, and about fifty other languages) — the demo scenario

above is captured in French on purpose, and a query in a different

language still finds it. Verified end-to-end

(scripts/check_multilingual.py).

---

Four ways to use Haki

1. Coded agent — SDK and CLI

*Python or TypeScript developers. A few lines around your existing LLM call.*

from haki import HakiClient

from haki.runtime import build_prompt_context, capture_turn

client = HakiClient("http://localhost:8100")

Before the LLM call: memory becomes an instruction block

packet = client.context(subject_id="usr_42", query=user_msg, project_id="prj") prompt = build_prompt_context(packet) + "\n" + system_prompt

answer = my_llm(prompt, user_msg) # your LLM and app code don't change

After the LLM call: the conversation turn goes back into memory

capture_turn(client, "usr_42", "prj", user_msg, answer)

SDK details (methods, async, errors)

• capture(events, idempotency_key) — idempotent ingestion: a network retry never creates a duplicate;
• context(subject_id, query, project_id, budget_tokens=2000) — the ContextPacket, with trace_id;
• inspect(trace_id) — why these memories were chosen;
• timeline(subject_id, project_id), consolidate_subject(...), facts(...), consolidate(), forget(...), health();
• Async variant: AsyncHakiClient;
• Typed errors: HakiApiError (error_type, field, status_code), HakiConnectionError.

CLI: haki login (device-code sign-in, see below), haki connect (configure and test with a key in hand), haki verify (timed memory test), haki status (API health), haki mcp (Cursor packaging).

`haki login` — for a Cloud account, the hk_ key is only ever shown once, at provisioning: the terminal has no way to retrieve it again. The device-code flow (RFC 8628) closes that gap without a new secret. The CLI shows an XXXX-XXXX code and opens /cli-auth with the code already filled in (verification_uri_complete); the code stays on screen too, so it can be typed by hand from a phone. You approve it in the console, already signed in — the terminal then receives a fresh, dedicated key, not the console's own — revoking that terminal from *Keys* disconnects nothing else. The key is served exactly once, by the poll that consumes it.

Server-side, HAKI_CONSOLE_SERVICE_KEY must be configured (it's what authenticates the console against /v1/cli/device/approve). Wrong codes are rate-limited per person, not per IP: every approval arrives from the same address (the console's own backend), so a per-IP counter would be a shared bucket any single user could exhaust for everyone else.

TypeScript SDK (parity with the Python SDK)

*Same methods, same typed errors, same block — zero runtime dependency (native fetch, Node 18+).*

cd sdk/typescript && npm install && npm run build && npm test

import { HakiClient, buildPromptContext, captureTurn } from "gethaki";

const client = new HakiClient({ baseUrl: "http://localhost:8100", apiKey: "hk_..." });

const { packet } = await client.context({ subjectId: "usr_42", query: userMsg, projectId: "prj" }); const prompt = buildPromptContext(packet) + "\n" + systemPrompt; const answer = await myLlm(prompt, userMsg); await captureTurn(client, { subjectId: "usr_42", projectId: "prj", userMsg, assistantMsg: answer });

CLI haki-ts (node dist/cli.js …): connect, verify, status — same ~/.haki/config.json file as the Python CLI, the two are interchangeable. Runnable example: sdk/typescript/examples/basic-agent.mjs.

2. Cursor — MCP server

*Cursor users. One-click install, no key to copy by hand.*

uv run haki mcp   # prints the deeplink, the mcp.json, and the Project Rule

1. The "Add Haki to Cursor" deeplink installs the MCP server;
2. The Project Rule (.cursor/rules/haki.mdc) tells the agent when to remember and when to recall;
3. Cursor then keeps decisions, conventions, and resolved bugs across sessions.

Four tools show up in Cursor:

Known, documented limit: MCP can't intercept every Cursor conversation —

the server only sees the tool calls Cursor decides to trigger. The Project

Rule tells the agent *when* to call them; real coverage is measured, never

presented as total.

3. n8n — template and nodes

*No-code builders. One template to import, three things to configure.*

Chain: Webhook → Haki Context → AI Agent → Haki Capture → Respond

Two options in integrations/n8n/:

• Native template haki-persistent-support-agent.json — importable into any n8n instance, no extra install (standard HTTP nodes);
• Node package n8n-nodes-haki — visual Haki Context and Haki Capture nodes, with built-in validation.

Three settings are all it takes: the Haki credential, the LLM credential, and the counterpart's identity (subject). A call with no identity is refused — a memory with no stable identity isn't reliable.

Verified against a real n8n instance (Docker): a preference stated in the

first message is recalled in the second, with its source.

4. OpenAI-compatible gateway

*Apps already speaking the OpenAI API. Only base_url changes — memory becomes automatic.*

import openai

client = openai.OpenAI( base_url="http://localhost:8100/gateway/v1", api_key="hk_...", # Haki key default_headers={"X-Haki-Subject-Id": "usr_42"}, # who to remember ) client.chat.completions.create(model="...", messages=[...])

On every POST /gateway/v1/chat/completions call: the subject's memory is injected at the top of the system message (a … block), the call is forwarded to the configured provider (HAKI_LLM_* — the Haki key itself is never sent upstream), the exchange is then captured (conversation.turn, idempotent), and consolidation resumes in the background. The response returned is the provider's own, unchanged, plus three headers: X-Haki-Memory, `