convez.ai
MCP ServerAutomaçãoIntermediário
Keyoku-ai

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 GitHub
BomPluginScore · de 0 a 100

MCP 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/keyoku

1 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

Estrelas
21
Forks
5
Acompanhando
1
Saúde
87%
Último commit
há 2 meses
Versão
v2.12.1
Issues abertas
4
Contribuidores
4

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.

npm CI TypeScript License: MIT

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 init from 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:

  1. Registers the MCP server — via claude mcp add --scope user, so Claude Code connects on next launch
  2. Installs the hooks — activity recording (every Bash/Edit/Write/Read/MCP call), a session-start brief, and prompt-time practice injection
  3. Wires Codex too — when ~/.codex exists, the MCP server lands in config.toml automatically (same tools, same workflows)
  4. Stays local — no cloud, no telemetry; state lives in ~/.keyoku with the same file permissions as ~/.aws. keyoku pause stops 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

ToolWhat it does
activity_record / activity_listLog and browse the observation stream
workflow_suggestMine patterns → model-refined draft workflows
workflow_capture"Save what I just did" — last N session actions become a draft
workflow_approve / workflow_updateSave or edit templates (slash commands stay current)
workflow_template_list / workflow_template_deleteManage the catalog
workflow_executeRun a template (params fill {{placeholders}})
execution_complete / execution_cancel / execution_listResume, stop, browse runs
knowledge_submit / knowledge_queryThe 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 varDefaultPurpose
KEYOKU_HOME~/.keyokuState directory
GEMINI_API_KEY / ANTHROPIC_API_KEY—Enable model-refined suggestions
KEYOKU_SLM_PROVIDERautogemini, 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.

Ver o original no GitHub

Bom para

Relacionados