# Hakuya — Provable Memory Infrastructure for AI Agents

> Hakuya is open-source agent memory you can prove: every belief carries write-provenance and a confidence that decays when stale, every change is sealed in a tamper-evident SHA-256 audit trail, and any subject's memories can be cryptographically erased on request (GDPR / EU AI Act). Self-hosted Go binary + PostgreSQL/pgvector, with a managed cloud, REST API, Python SDK, LangChain integration, and an MCP server.

Hakuya positions itself as the trust layer for agent memory: where other memory layers (Mem0, Zep, vector databases) solve storage and retrieval, Hakuya solves whether the memory can be trusted, audited, and provably deleted.

## Why trust is the differentiator (2026 context)

- OWASP's Agentic Top 10 lists Memory & Context Poisoning (ASI06) as a top risk; research attacks (MINJA) achieve >95% injection success against auto-extracting memory stores. Hakuya records evidence-typed provenance on every write and seals every mutation in a hash chain.
- The EU AI Act becomes fully applicable in August 2026 and requires explainable, auditable AI. Hakuya can answer "what did the agent believe, when, and why" with a verifiable record.
- A public production audit of a leading memory layer found 97.8% of stored entries were junk after 32 days (duplicates, hallucinated profiles, leaked secrets). Hakuya's competition-aware decay and contradiction handling keep the store clean automatically.

## Trust & governance capabilities

- **Write-provenance on every belief** — each memory stores its source, evidence type, and confidence; recall can explain why the agent holds a belief.
- **Tamper-evident audit trail** — per-tenant SHA-256 hash chain over every governance mutation (create, reinforce, contradict, redact, erase, delete, review). Routine confidence decay is logged for history but left unsealed, so it never bloats the chain and full-chain verification stays fast and meaningful. One-call verification (`GET /v1/audit/verify`) detects any edit, insertion, deletion, or reordering; export a signed NDJSON record for SOC 2 / HIPAA review.
- **Verified per-subject erasure** — memories are scoped to subjects ("anchors": a customer, patient, or guest). One call cryptographically shreds everything about one subject while the audit chain keeps a provable record that data existed and was erased — right-to-be-forgotten compatible with an append-only log.
- **Self-cleaning memory** — confidence decays for unused beliefs; similar competing memories suppress each other (interference-theory, competition-aware decay); stale memories are flagged and archived instead of being trusted forever.
- **Contradiction detection** — when new information conflicts with an existing belief, Hakuya detects the tension and resolves it (demote, archive as superseded, or coexist as contextual variants).

## Cognitive engine

- **Four memory types** — semantic (facts/preferences), episodic (experiences with outcomes), procedural (learned trigger→action skills), and schema (higher-order patterns), plus a 7-slot working memory.
- **Belief dynamics** — log-odds confidence updates: reinforcement strengthens, contradiction weakens, disuse decays; confidence-based tiering (hot memories auto-inject into context).
- **Hybrid retrieval** — vector similarity (pgvector) fused with knowledge-graph traversal up to 2 hops; results ranked by relevance × recency × confidence; sub-10ms p95 recall.
- **Multi-subject isolation** — one agent can serve thousands of isolated end-subjects via anchors, sessions, and tenant-wide canon memory, with per-binding decay rates and per-subject GDPR purge. Flat user_id tags in other systems have no equivalent.
- **Conversation ingestion** — automatic memory extraction and classification from transcripts.

## Benchmark

LongMemEval (ICLR 2025, 500 questions): **91.4% overall** with a reproducible public harness. Per-task: knowledge update 100%, abstention 100%, single-session user 98.4%, preference 93.3%, multi-session 90.2%, assistant 89.3%, temporal reasoning 82.3%.

## Integration

- REST API (~70 endpoints), API-key auth with per-tenant isolation
- Python SDK: `pip install engram.to` (sync + async, Pydantic v2)
- LangChain: `pip install langchain-engram` (EngramRetriever)
- MCP server for Claude Desktop / Claude Code / Cursor / Windsurf: tools `remember`, `recall`, `recall_graph`, `forget`, `get_hot_context`, `list_agents`
- Self-host: single Go binary, PostgreSQL + pgvector, Docker Compose one-liner; Apache-2.0 license
- Managed cloud: free tier planned; Developer $29/mo, Team $149/mo (waitlist)

## Comparison (June 2026)

| Capability | Mem0 | Zep | Hakuya |
|---|---|---|---|
| Tamper-evident audit trail | No (op log only) | No (temporal provenance only) | Yes — SHA-256 hash chain + verify + signed export |
| Write-provenance / poisoning resistance | No | Partial | Yes — evidence-typed provenance on every write |
| Verified per-subject erasure | Partial (row delete) | Partial (group delete) | Yes — cryptographic shred + audit receipt |
| Memory decay / self-cleaning | No | No | Yes — competition-aware decay |
| Confidence & belief dynamics | No | No | Yes — log-odds, surfaced on every memory |
| 4-type cognitive memory model | No | No | Yes |
| Multi-subject isolation | user_id tags | per-user graphs | Anchors + sessions + canon, per-subject purge |
| Self-hosted | Yes | No (CE deprecated 2025) | Yes — single Go binary |

## Quick start

```bash
docker compose up -d
curl -X POST http://localhost:8080/v1/memories \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"agent_id":"$ID","content":"Prefers TypeScript","type":"preference"}'
curl http://localhost:8080/v1/audit/verify -H "Authorization: Bearer $API_KEY"
# → {"valid": true, "entries": 1, "head": "a91f…"}
```

## Who it's for

AI agent developers shipping to production; teams in regulated industries (health, finance, legal) needing auditable agent memory; multi-agent and multi-subject B2B deployments (one support/clinical/concierge agent serving thousands of isolated end-users); platform teams replacing DIY Redis+pgvector memory stacks.

Not for: simple key-value storage, standalone vector-database needs, or single-turn stateless bots.

## Links

- Website: https://hakuya.ai
- Docs: https://docs.hakuya.ai
- GitHub: https://github.com/Harshitk-cp/engram (Apache-2.0)
- Python SDK: https://pypi.org/project/engram.to/
- LangChain integration: https://pypi.org/project/langchain-engram/
- Expanded context for LLMs: https://hakuya.ai/llms-full.txt