haki

Haki 的作用

如今，AI Agent 除了单次对话之外什么都记不住：每次新会话都会从头开始，重新解释上下文，还可能套用数月前就已过时的偏好，却无从察觉。

Haki 是一个开源（Apache-2.0）的持久记忆层，不依赖你使用的模型或框架：它会从 Agent 的交流中提取结构化事实，随着时间推移保持信息更新，并为每个新请求提供相关、注明日期和来源的上下文包。它完全由你掌控——只需运行一次 docker compose up 即可安装，且不会更改你现有的 Agent、模型和基础设施。

问题

在生产环境中构建 AI Agent 的团队总会遇到相同的局限：

现有方案（通用向量存储、对话摘要）在演示中表现良好，但在数周的真实使用后就会退化：将过时信息当作当前信息提供、矛盾未被发现、完全无法解释。

方案

事实台账，而非对话历史。 Haki 不会归档原始消息以供日后重放，而是从中提取结构化事实——偏好、约束、决策——并将每条事实关联回支撑它的来源事件。

双时态与替代关系。 每条事实都带有明确的有效日期和状态。信息发生变化时，旧事实会被标记为已替代——绝不会悄然删除，也绝不会再作为当前信息提供。出现尚未解决的矛盾时，两个版本都会被暂缓提供并标记出来，而不是随机提供其一。

系统化追溯。 每个注入的上下文包都附带其来源、有效日期和追踪记录，说明保留、排除或阻止了哪些记忆，以及原因。“Agent 为什么使用这条信息？”——不到一分钟就能给出可验证的答案。

快速入门

前置条件：Docker 和 uv。.env.example 中的默认值足以开始使用——无需密钥。如需自定义配置（真实的大模型密钥等），请将该文件复制为 .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

如果遇到问题，运行 bash scripts/doctor.sh，即可通过一条命令诊断 Docker、容器、Postgres、.env、迁移和 API——只读、无副作用，可按需反复运行。

在另一个终端中，验证一切是否正常：

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

haki verify 会在几秒钟内运行一个完整场景：记录一条偏好，然后在同一段对话中更改想法，接着在新一段对话中查询记忆。它必须返回当前值，将旧值保留并标记为 superseded，而不是将其删除，并将整个过程关联到一条追踪记录。

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

如果仍然返回过时的值，或者找不到标记为 superseded 的旧值，该命令就会以状态码 1 退出：如果两条事实之间没有关联，仅仅碰巧返回了正确的值，就不算真正更新了记忆。

默认支持多语言：本地嵌入模型支持多种语言（法语、英语、西班牙语及另外约 50 种语言）——上方的演示场景特意用法语记录，即使使用不同语言查询，也仍然可以找到这条记忆。已通过端到端验证（scripts/check_multilingual.py）。

使用 Haki 的四种方式

1. 编码 Agent——SDK 和 CLI

面向 Python 或 TypeScript 开发者。在现有的大模型调用外添加几行代码即可。

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（与 Python SDK 功能一致）

相同的方法、相同的类型化错误、相同的 <haki_memory> 块——无运行时依赖（使用原生 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——与 Python CLI 使用同一个 ~/.haki/config.json 文件，两者可以互换使用。可运行示例：sdk/typescript/examples/basic-agent.mjs。

2. Cursor — MCP 服务

面向 Cursor 用户。一键安装，无需手动复制密钥。

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

1. “Add Haki to Cursor” 深度链接会安装 MCP 服务；
2. 项目规则（.cursor/rules/haki.mdc）会告诉 Agent 何时记住、何时回忆；
3. Cursor 随后会在不同会话间保留决策、约定和已解决的 Bug。

Cursor 中会显示四个工具：

已知且有文档记录的限制：MCP 无法拦截 Cursor 中的每次对话—— 服务只能看到 Cursor 决定触发的工具调用。项目规则会告诉 Agent 何时 调用这些工具；实际覆盖率会进行衡量，绝不会宣称达到 100%。

3. n8n — 模板和节点

面向无代码构建者。导入一个模板，配置三项内容即可。

链路：Webhook → Haki Context → AI Agent → Haki Capture → Respond

integrations/n8n/ 中有两个选项：

• 原生模板 haki-persistent-support-agent.json — 可导入任何 n8n 实例，无需额外安装（使用标准 HTTP 节点）；
• 节点包 n8n-nodes-haki — 提供可视化的 Haki Context 和 Haki Capture 节点，并内置验证功能。

只需设置三项：Haki 凭据、LLM 凭据，以及对方的身份标识（subject）。没有身份标识的调用会被拒绝——没有稳定身份标识的记忆不可靠。

已在真实的 n8n 实例（Docker）中验证：第一条消息中提到的偏好会在第二条消息中被回忆，并附有来源信息。

4. 兼容 OpenAI 的网关

面向已使用 OpenAI API 的应用。只需更改 base_url，记忆便会自动生效。

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=[...])

每次调用 POST /gateway/v1/chat/completions 时：会将主体的记忆注入系统消息顶部（以 <haki_memory>…</haki_memory> 块的形式），再将调用转发给已配置的提供方（HAKI_LLM_*——Haki 密钥本身绝不会发送到上游），随后记录这次交互（conversation.turn，具备幂等性），并在后台继续进行整合。返回的响应与提供方原始响应完全相同，另外附带三个标头：X-Haki-Memory、X-Haki-Trace-Id、X-Haki-Context-Ms。

• 身份信息通过标头传递，绝不放在请求正文中（模型绝不会决定要记住什么）：X-Haki-Subject-Id（记忆所必需）、X-Haki-Thread-Id、X-Haki-Run-Id、X-Haki-Purpose、X-Haki-Idempotency-Key（默认值为正文的哈希值——重试不会产生重复内容）。
• 可控降级：没有身份标识时，请求会原样通过（X-Haki-Memory: disabled）；如果无法构建上下文，请求仍会发出，并标记为 degraded。Haki 绝不会阻止 Agent。
• 流式响应：stream: true 会直接透传（X-Haki-Memory: disabled，不注入，也不捕获）——这是经过考虑的选择：无法捕获最终响应时进行注入会破坏记忆循环，而缓冲整个流则会违背使用流式响应的初衷。
• 有文档记录的限制（见私有仓库中的 research/Haki_Memory_Runtime.md）：网关会观察对模型的调用，但看不到 Agent 在两次调用之间于本地运行的工具——这些调用通过 SDK 或直接调用 API 捕获。

SDK 中也有 httpx 变体：haki.gateway.gateway_client(base_url, api_key, subject_id, ...)（以及 async_gateway_client）。记忆带来的开销主要来自 build_context（本地约 15 ms，/v1/context 的 p95 低于 250 ms）——可复现的基准测试：

uv run python scripts/benchmark_gateway.py --api-key hk_...

托管云

不想运行自己的基础设施？ gethaki.space 提供相同的 API，此外还有一个 Web 控制台，可用于浏览记忆、检查 追踪记录并手动解决冲突。完全支持免费自托管——本仓库中的 API 与 Cloud 运行的 API 相同。

工作原理

flowchart LR
    A[Incoming message] --> B[CAPTURE<br/>raw evidence,<br/>append-only]
    B --> C[CONSOLIDATION<br/>extraction, dedup,<br/>supersession, conflicts]
    C --> D[(MEMORY<br/>active facts,<br/>dated, sourced)]
    D --> E[CONTEXT<br/>relevant packet,<br/>under budget,<br/>249ms p95]
    E --> F[Agent and LLM]
    F --> B
    E -.-> G[INSPECT<br/>decision trace]
    D -.-> H[FORGET<br/>propagated erasure,<br/>with a receipt]

1. 捕获 — 应用发送一个事件（一条消息、一个操作、一项 工具结果）。Haki 会将其记录为不可变证据，并在几毫秒内回复。网络重试 不会产生重复项（幂等性）。
2. 整合 — Haki 在后台读取事件，并判断哪些内容应成为持久事实。它会去重、检测变化（旧 事实会变为已取代）以及矛盾（状态为冲突，在解决前暂不提供）。事实由 **（主体、谓词、限定条件）**标识：“工作日的起床时间”和“周末 的起床时间”是两个不同且共存的事实，并不矛盾—— 无论措辞多么接近，不同的限定条件都不会被混为一谈。
3. 上下文 — Agent 在每次回复前都会请求相关记忆。 Haki 只返回有效、当前有效且在范围内的事实，按相关性排序， 并严格控制 Token 预算——在 10,000 条事实上的测量结果为 p95 249 毫秒 （参见 scripts/benchmark_context.py）。
4. 检查 — 随时都可以通过追踪记录了解某条信息为何被保留、排除或拦截。
5. 遗忘 — 更正或擦除操作会传播到所有由其衍生的内容，并附带带时间戳的回执。

概念

定位

实测性能

可复现的基准测试：uv run python scripts/benchmark_context.py（每种规模 100 次请求，本地嵌入，Windows 开发机器）。

嵌入在本地计算（CPU 上运行 ONNX，使用多语言 384 维模型）——关键路径中没有网络调用。检索结合向量 索引（hnsw）和全文索引（GIN），然后只对最佳候选项进行评分。大模型成本（信息提取）完全异步，不会拖慢 回复。

公开基准测试

Haki 发布的是可复现的基准测试工具，而不是经过筛选的数据：包含冻结且带版本号的配置（数据集和校验和、模型、提示词、预算、价格）、严格遵循相同协议重新运行的完整上下文基线（相同模型、相同提示词、相同评审器），以及这个领域鲜少公布的指标——矛盾泄漏率、弃答率、每个数据包的令牌数、延迟和成本。

• 工具：eval/（LoCoMo 和 LongMemEval_S 加载器、流水线、评审器、报告）。
• 我们有意不将结果提交到此代码库——请自行使用指定的数据集和冻结的配置运行工具；生成的数值（写入 eval/results/，已加入 gitignore）由你自行判断是否可信或提出质疑，而不是我们挑选给你看的数字。
• 复现：具体命令见 eval/README.md。

API 一览

以下 curl 示例假设已有密钥：使用 curl -X POST http://localhost:8100/v1/keys -d '{"org_id":"org_acme","project_id":"prj_support","label":"dev"}' 创建密钥（第一个密钥免费，此后每个密钥管理自己的项目），然后在每次调用中添加 -H "Authorization: Bearer hk_..."。

错误类型明确且可采取行动： {"error": {"type": "missing_scope", "message": "...", "field": "..."}} ——不会返回笼统的错误消息。

# Capture a preference
curl -X POST http://localhost:8100/v1/capture \
  -H "Content-Type: application/json" \
  -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-07-15T10:00:00Z",
      "payload": {"role": "user", "content": "I prefer my invoices in French."},
      "classification": ["customer-data"]
    }]
  }'

# Consolidate (extracts the durable fact)
curl -X POST http://localhost:8100/v1/consolidate

# Ask for memory before a response
curl -X POST http://localhost:8100/v1/context \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_support", "subject_id": "usr_42",
    "query": "what language should the invoice be in?",
    "budget_tokens": 2000
  }'

安全性、作用域与遗忘

• 按项目划分的 API 密钥：默认情况下，每次 /v1/* 调用都需要 Authorization: Bearer hk_...。密钥仅绑定到单个项目：请求其他项目会返回 403 forbidden_scope，且绝不会泄露其他项目的存在。通过 POST/GET/DELETE /v1/keys 管理（详情见 docs/SECURITY.md）。
• PostgreSQL 行级安全：隔离由数据库本身保障（对 events、facts、traces、conflicts 启用 RLS）——即使应用层过滤被遗漏，查询也无法跨越项目边界（已通过非披露测试验证）。
• 确定性策略引擎：每次读取和写入都会经过明确的规则检查（作用域存在、密钥与项目匹配、审计）——绝不交由大模型处理。
• 模型绝不选择作用域：project_id 和 subject_id 来自调用方后端或其配置，绝不来自 LLM。
• 反馈与纠正：POST /v1/feedback （useful/irrelevant/incorrect——被标记为不正确的事实会变为 disputed，且不再提供）；POST /v1/conflicts/{id}/resolve 用于解决矛盾，并保留完整历史记录。
• 密钥：LLM 密钥存放在 .env 中（已被 git 忽略，并提供模板，见 .env.example），绝不放在代码、终端或前端中。
• 真正的遗忘：POST /v1/forget 会将擦除操作传递至 facts、 embeddings、events 和 traces，并在 forget_receipts 中生成带时间戳的回执。
• 提供开放的开发模式（HAKI_AUTH_REQUIRED=false），仅供本地使用，启动时会显示明确警告。

架构

质量与测试

针对真实 PostgreSQL 数据库运行了 376 项 Python 测试和 14 项 Node 测试（不使用数据库模拟）：uv run pytest 和 cd sdk/typescript && npm test。

测试验证行为保证，而非实现细节：

• 被取代的事实绝不会作为有效事实返回；
• 一个主体绝不会看到另一个主体的记忆；
• 网络重试绝不会创建重复项；
• 存在未解决的冲突时，相关的两条事实都会被暂缓；
• 忘记之后，任何内容都不会再次被提供；
• 非法状态转换会被拒绝；
• 网关会注入记忆、在不阻塞的前提下降级、转发上游错误，并确保每个幂等键只捕获一次。

已在真实环境中运行端到端检查：LLM 提取（OpenRouter）、MCP 服务（官方客户端）、n8n 工作流（Docker）、延迟基准测试。

当前各项保证及其对应的实现机制和验证测试，均记录在 docs-site/en/production-guarantees.mdx 中。

路线图

仓库结构

haki/
├── app/                 # FastAPI API (ledger, consolidator, context, gateway, MCP)
├── sdk/python/          # SDK + haki CLI
├── sdk/typescript/      # TypeScript SDK + haki-ts CLI (Python parity)
├── integrations/n8n/    # Native template + e2e workflow (node package: github.com/GetHaki/n8n-nodes-haki)
├── alembic/             # PostgreSQL migrations
├── tests/               # Behavioral tests (incl. eval harness tests)
├── eval/                # Public benchmark harness (LoCoMo + LongMemEval)
├── scripts/             # Benchmarks and diagnostics
├── docs-site/           # Product documentation (Mintlify)
└── docker-compose.yml   # Postgres + pgvector + Redis

这是可自托管的 OSS 核心：API、两个 SDK、MCP 服务、n8n 集成和公开评测工具。托管版 Web 控制台（浏览记忆、点击解决冲突、计费）属于 Cloud 服务，存放在单独的私有仓库中——自托管 Haki 绝不需要它。

文档

产品文档（指南、完整 API 参考、生产保证契约）位于 docs-site/en/——这是一个 Mintlify 站点，可在该目录中运行 mint dev 在本地启动（需要 Node 18/20/22 LTS）。法语译文在 docs-site/fr/ 中同步维护。