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)

TypeScript SDK (parity with the Python SDK)

Same methods, same typed errors, same <haki_memory> 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: