Keyoku watches how you work in Claude Code or Codex, turns the goals you actually finish into reusable workflows, and brings them back the next time — your agent reaching for what already worked, before you ask. A TypeScript MCP server and CLI in a single npm package.
Local-first. No cloud, no telemetry. Reuse needs zero API keys — the coding agent itself is the judge.
Keyoku covers the full loop: trace what you do, mine what repeats, surface it proactively, and run what you approve — with knowledge, connectors, goals, and an audit trail around it.
Muscle memory
Goals you converge become reusable workflows — reused with no API key.
When a goal's machine-checkable criteria all pass, its action trace promotes into a learned workflow — captured live via goal_focus, recorded explicitly, or back-filled from the activity log (keyoku backfill repairs older empty ones). On a similar later goal, your coding agent — not a second model — judges which learned workflow applies, so reuse needs zero API keys and matches by meaning, not just shared words. Suggestions self-prune by what actually recurs, and failed approaches are kept as pitfalls (negative memory).
Activity tracing
Hooks record every Bash, Edit, Write, Read, and MCP tool call.
Events land in ~/.keyoku/activity.jsonl (size-capped ~10k events), with secrets redacted at record time. Successful connector calls are recorded too. `keyoku pause` / `resume` is the privacy switch.
Pattern mining
Heuristic detection of 2–6 step sequences that repeat at least 3 times.
Mined within each session, counted across sessions, with non-overlapping occurrence counting. Sequences need at least one ACTION step. Detections route as automation (runnable) or practice (filed as knowledge) — and workflow_capture saves what you just did without waiting for repetition.
Proactive surfacing
The server tracks pattern ripeness in the background; hooks deliver it.
PostToolUse injects a one-time nudge when a pattern crosses threshold, SessionStart briefs the agent on available workflows and unsaved patterns, UserPromptSubmit injects matching workflows and house patterns. Each pattern surfaces exactly once.
One-command workflows
Approve a suggestion and it becomes a template you can run anywhere.
Approved workflows publish as MCP prompts — native slash commands in Claude Code. Templates support bash, mcp_call, agent_prompt, and human_review steps; params fill {{placeholders}}; executions persist step-by-step and resume in order. Bake them as skills or AGENTS.md blocks with `keyoku export`.
Knowledge layer
Facts about connectors, conventions, and practice — queried at prompt time.
Auto-seeded from connector tool descriptions, mined practice patterns, agent research, and CLAUDE.md conventions. Set KEYOKU_ENGINE_URL and queries upgrade to semantic search via keyoku-engine, with silent local fallback.
Connectors
Register external MCP servers — stdio, HTTP, or synthesized from an OpenAPI spec.
Each connector gets an autonomy level: observe, suggest, approve, or autonomous. Approval-gated calls queue for your sign-off.
Goals
Convergence mode: define machine-checkable criteria and let the harness keep checking.
Probes are command, http, or mcp calls with assertions, evaluated deterministically — a transport-failure guard prevents false convergence, and drift is detected if a met goal regresses. Re-assess on demand or run a CLI watch loop. Convergence is also what feeds muscle memory: a converged goal's trace becomes a reusable workflow.
Audit trail
Every action lands in an append-only audit log.
Inspect it with the audit_list tool or `keyoku audit` from the CLI.
Fact sheet
The essentials.
Item
Detail
Package
keyoku on npm — MCP server + CLI in one
Language
TypeScript
License
MIT
Repository
github.com/Keyoku-ai/keyoku
Tests
260+ (plus a CI muscle-memory retrieval eval)
State
~/.keyoku (directory mode 0700, files 0600)
Hooks
Three, installed by init: PostToolUse (record), SessionStart (brief), UserPromptSubmit (context)
Agents
Claude Code and Codex wired by keyoku init; Cursor and any MCP client via standard registration
Engine
keyoku-engine (Go, BSL 1.1) — optional brain for semantic search, via KEYOKU_ENGINE_URL
Keyoku vs Keyoku Engine
Two pieces, clearly split.
keyoku (TypeScript, MIT) is the workflow harness on this page — fully functional on its own. keyoku-engine (Go, BSL 1.1) is the optional brain: set KEYOKU_ENGINE_URL and the knowledge layer mirrors into it, upgrading knowledge_query to semantic search (embedder-only — Ollama works; no engine-side LLM needed), with silent local fallback. See the Engine docs.
Quick start
One command.
# Registers the MCP server (Claude Code + Codex) and three hooks
keyoku init
# Restart Claude Code, then verify everything
keyoku doctor
Dive deeper.
Follow the quickstart, see the full pipeline, or jump straight to the tool reference.
