Keyoku — Memória muscular para fluxos de código
Keyoku-ai/keyoku
Rastreamento de atividade + detecção de padrões = workflows de um comando
Ver no GitHubMCP server que registra automaticamente suas atividades no Claude Code, Cursor e Codex, detecta padrões repetidos e transforma ações frequentes em workflows executáveis com um comando. Aprende localmente, sem nuvem, e integra-se nativamente aos seus editores.
Instalação
npx convez-ai Keyoku-ai/keyoku1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar sequências repetitivas de edição e refatoração de código
- Capturar rotinas de desenvolvimento (testes, deploys, linting) em workflows reutilizáveis
- Compartilhar fluxos de trabalho padronizados com times via exports de skills
Veredito

Ferramenta robusta que endereça um problema real: repetição de instruções ao agente. Execução puramente local, integração direta com IDEs e sem dependências de cloud. Requer engajamento ativo para aprovação de workflows, mas o payoff escala bem em equipes com padrões de desenvolvimento consolidados.
README
A tradução para o português deste README ainda está na fila.
Get Started
Install it once, then wire it up:
npm install -g keyoku
keyoku init
A global install keeps keyoku on a durable path. Running
npx keyoku initfrom the throwaway npx cache is refused — npm can evict that directory and break the hooks — so install globally first.
The init command wires everything automatically:
- Registers the MCP server — via
claude mcp add --scope user, so Claude Code connects on next launch - Installs the hooks — activity recording (every Bash/Edit/Write/Read/MCP call), a session-start brief, and prompt-time practice injection
- Wires Codex too — when
~/.codexexists, the MCP server lands inconfig.tomlautomatically (same tools, same workflows) - Stays local — no cloud, no telemetry; state lives in
~/.keyokuwith the same file permissions as~/.aws.keyoku pausestops everything instantly.
Restart Claude Code and keyoku is live. Then skip the cold start entirely:
keyoku import # backfill months of history from your Claude Code transcripts
Now ask your agent to run workflow_suggest — keyoku mines your real history immediately instead of waiting days for new activity. Approved workflows appear as native slash commands (MCP prompts), and keyoku export <slug> bakes one into your repo as a Claude Code skill your whole team inherits.
How It Works
Without Keyoku: you describe the same multi-step process to your agent every session.
With Keyoku: you approve a workflow once, then run it with one command. The agent never has to rediscover it.
1. Activity tracing — automatic
Every tool call your agent makes is recorded as a lightweight ActivityEvent — tool name, summary, extracted entities. Purely local.
2. Pattern detection — heuristics for recall, a model for precision
workflow_suggest mines recurring sequences from your recent activity (non-overlapping counting, noise suppression, longest-chain collapsing — no model required). If an SLM key is configured (GEMINI_API_KEY or ANTHROPIC_API_KEY), the model then refines the drafts: filters coincidences, names workflows properly, and parameterizes run-specific values with {{placeholders}}.
3. Approval — you are the trust boundary
workflow_approve { slug: "deploy-staging", name: "Deploy staging", steps: [...] }
Review the draft like you'd review a shell script, then approve. Templates live in ~/.keyoku/templates.json.
4. Execution — bash runs, judgment pauses
workflow_execute { slug: "deploy-staging" }
- bash steps run directly (per-step
cwd, timeouts, output captured) - agent_prompt steps pause and hand the step to your coding agent, which resumes with
execution_complete - human_review steps wait for your explicit sign-off
Every execution persists step-by-step — crash-safe, fully inspectable via execution_list.
MCP Tools
| Tool | What it does |
|---|---|
activity_record / activity_list | Log and browse the observation stream |
workflow_suggest | Mine patterns → model-refined draft workflows |
workflow_capture | "Save what I just did" — last N session actions become a draft |
workflow_approve / workflow_update | Save or edit templates (slash commands stay current) |
workflow_template_list / workflow_template_delete | Manage the catalog |
workflow_execute | Run a template (params fill {{placeholders}}) |
execution_complete / execution_cancel / execution_list | Resume, stop, browse runs |
knowledge_submit / knowledge_query | The context layer — research, conventions, practice |
goal_create / goal_assess / … | Goals with machine-checkable success criteria |
connector_add / connector_call / … | Plug in external MCP servers (GitHub, GCP, …) with autonomy gating |
CLI
keyoku [serve] Start the MCP server on stdio (Claude Code does this automatically)
keyoku init Wire up the hook + MCP registration
keyoku import Backfill activity from Claude Code + Codex transcripts (kills the cold start)
keyoku export <slug> Bake a workflow into ./.claude/skills — or AGENTS.md with --agents-md
keyoku pause | resume Privacy switch: stop/start all recording and injection
keyoku doctor Verify hooks, MCP registrations, engine, and activity health
keyoku status Show goals, templates, connectors
keyoku learn Mine patterns from the activity log
keyoku assess <goal> One-shot convergence check
keyoku watch <goal> Re-assess on an interval
keyoku approvals Approve/deny gated connector calls
keyoku audit [n] Show the audit trail
Architecture
Your machine
├── Claude Code (or Cursor, Codex)
│ ├── PostToolUse hook → keyoku record (activity logging)
│ └── MCP connection → keyoku serve (tool calls)
│
└── ~/.keyoku/
├── activity.jsonl (event stream, capped)
├── templates.json (approved workflows)
├── executions.json (run history)
├── goals.json (convergence targets)
└── connectors.json (external MCP services)
The division of labor: heuristics generate candidates for free, the small model refines them cheaply, and your coding agent does the heavy lifting on the subscription you already pay for. Keyoku orchestrates; it never burns frontier tokens.
Configuration
| Env var | Default | Purpose |
|---|---|---|
KEYOKU_HOME | ~/.keyoku | State directory |
GEMINI_API_KEY / ANTHROPIC_API_KEY | — | Enable model-refined suggestions |
KEYOKU_SLM_PROVIDER | auto | gemini, anthropic, openai-compat, or none |
KEYOKU_SLM_BASE_URL / KEYOKU_SLM_MODEL | — | Any OpenAI-compatible endpoint (Ollama, LM Studio, LiteLLM, Groq, …) |
KEYOKU_ENGINE_URL | — | Connect a running keyoku-engine: knowledge mirrors into it and queries upgrade to semantic search |
KEYOKU_DEBUG | — | Full error stacks |
Security
Approved templates execute shell commands with your privileges — the approval step is the trust boundary. Read SECURITY.md before installing.
keyoku-engine
The Go backend for teams: knowledge graph, semantic search, memory decay, and cross-device sync. Available at github.com/Keyoku-ai/keyoku-engine.
License
MIT — see LICENSE.