HTTP API
RESTful JSON endpoints with Bearer token auth.
All memory operations, heartbeat checks, scheduling, team management, and SSE event streaming.
Engine / Overview
Keyoku Engine.
A single Go binary that gives your AI agent long-term memory, a knowledge graph, and a pure-SQL heartbeat system. SQLite storage, HNSW vector search, no cloud dependency.
One binary. One file. Portable anywhere.
Architecture
Four layers, one process.
The engine runs as a single process with an embedded HTTP server. No external databases, no message queues, no infrastructure. SQLite handles persistence, HNSW handles vector search, and everything runs in-process.
Memory engine
LLM-powered extraction, 3-tier dedup, conflict detection, and composite ranking.
Handles the intelligence layer between raw data and storage, including decay calculations.
Storage
SQLite with WAL mode for concurrent reads.
HNSW index for vector similarity search. LRU hot cache for frequently accessed memories. Full-text search as fallback.
Heartbeat
14-signal scanner with confluence scoring and adaptive cooldowns.
Quiet hours, topic dedup, and fingerprint-based suppression. Decides when your agent should act.
Features
What the engine does.
Keyoku handles the full memory lifecycle: capture, deduplicate, store, decay, retrieve, and signal. Your agent gets persistent context without managing any of it directly.
Structured memory extraction
Every conversation exchange is analyzed by an LLM to extract typed memories.
Facts, preferences, relationships, tasks, entities — with importance scores, confidence levels, and sentiment.
HNSW vector search
In-process approximate nearest neighbor search using HNSW indexing.
Sub-millisecond retrieval for hot memories, with LRU caching and SQLite full-text fallback.
Ebbinghaus decay
Memories decay naturally over time based on their type.
Identity facts last ~365 days, ephemeral context ~3 days. Access frequency extends stability logarithmically.
Knowledge graph
Automatic entity and relationship extraction from conversations.
People, organizations, locations, and products are linked with 40+ relationship types and bidirectional inference.
14-signal heartbeat
Pure SQL heartbeat scan detects action triggers — LLM used only for optional analysis.
Detects deadlines, stalled work, conflicts, sentiment shifts, and more. Confluence scoring prevents false triggers.
Three-tier deduplication
Exact hash match, semantic similarity, and near-duplicate detection.
Thresholds at 0.95+ and 0.85-0.95 prevent redundant storage while preserving new information through merging.
Requirements
What you need.
| Requirement | Note |
|---|---|
Go 1.21+ | Build from source |
SQLite 3.35+ | Bundled via go-sqlite3 |
LLM API key | Gemini, OpenAI, Anthropic, or Ollama |
64MB RAM | Typical idle footprint |
~50MB disk | Binary size |
Quick start
Running the engine.
# Set required env vars
export KEYOKU_SESSION_TOKEN="your-secret-token"
export KEYOKU_EXTRACTION_PROVIDER="gemini"
export GEMINI_API_KEY="your-api-key"
# Run the binary
./keyoku-engine
# Health check
curl http://localhost:18900/api/v1/healthDive deeper.
Explore the full API reference, configuration options, memory system internals, heartbeat mechanics, and deployment guides.