ProactiveAgent

Memória proativa e sugestões entre ferramentas para Claude Code, Kimi Code, Cline, Cursor. Ensine uma vez, use em qualquer lugar.

GitHub

Experimente este MCPPatrocinado

Documentação

ProactiveAgent 🧠

Ensine uma vez, use em qualquer lugar. Faça Claude Code / Kimi Code / Cline / Cursor / Proma compartilharem a mesma "memória proativa" — ela não apenas lembra de tudo que você ensinou, mas também toma a iniciativa de lembrar você no momento certo. Com um único MCP montado, todos os agentes ganham capacidade proativa imediatamente.

Diferente de outras ferramentas de memória que "apenas lembram": ProactiveAgent lembra e também fala proativamente quando acha que deve lembrar você — correção, acompanhamento, automação, tarefas e habilidades, cinco tipos de sugestões proativas.

中文 · English

🎬 História de validação (entenda o que ele faz em 30 segundos)

Todo o conteúdo é resultado de execução real em 2026-08-05, não uma demonstração animada: Claude Code grava memória → Kimi Code recupera diretamente (100% de precisão); correção de comportamento / necessidade periódica → sugestão proativa acionada e aceita.

👉 Abra a página de demonstração interativa: Demonstração online (GitHub Pages) (basta abrir no navegador)

⚠️ A página blob do GitHub é apenas um visualizador de código e não executa scripts HTML. Use o link Pages acima para ver a demonstração interativa.

Cenário	Resultado do teste
Compartilhamento entre ferramentas	Claude Code `memory_capture` grava → Kimi Code `memory_recall` recupera com precisão (relevância 100%, zero configuração)
Sugestão proativa: correção	"Escreva testes unitários antes de commitar" → `suggest_now` identifica sugestão de correção → `suggest_accept` aceita → feedback retorna
Sugestão proativa: automação	"Verifique o progresso do projeto todos os dias às 17h" → `suggest_now` identifica sugestão de automação → aceita e entra no agendamento
Kimi integração com um comando (testado em 12/08)	`/plugins install .../kimi-plugin.zip` → sessão `kimi` comum ganha memória proativa automaticamente (modelo captura ativamente conforme instruções do plugin → recall em nova sessão, sem precisar de `--agent`)
Kimi proatividade em três vias (testado em 12/08)	Com hooks restaurados, fluxo completo: início da sessão injeta sugestões/perfil (today-push) → sinais fortes durante o processo `<notification>` são transmitidos (kimi-user-prompt) → encerramento consolida memória automaticamente (kimi-session-end, padrão aguardando confirmação)
Interoperabilidade UMP (testado em 12/08)	`ump-export` exporta → `@universalmemoryprotocol/core` oficial carrega 5/5 + recall (scope.owner) com 100% de precisão — memória não fica presa a nenhuma ferramenta

Por que vale a pena usar

🎯 Memória é "ativo do usuário", não "ativo da ferramenta"

As preferências que você ensina no Claude Code valem automaticamente no Kimi Code e no Cline — porque a memória fica em ~/.proma-proactive/, e todos os agentes leem e escrevem a mesma memória através do mesmo servidor MCP.

Diga adeus ao "preciso ensinar de novo em cada ferramenta": ensine a preferência de TypeScript uma vez, e todos os agentes lembram.

💡 Falar proativamente: silêncio quando deve silenciar

Não é um push tagarela, mas sim falar apenas com sinal, com moderação parametrizada:

Você corrigiu o agente → sugere gravar a regra na memória de longo prazo (evita reincidência)
Você repete a mesma ação → sugere automatizar / consolidar como fluxo
Conversa casual, recusa, horário de não perturbar → silêncio (isso é uma capacidade)
Moderação tem parâmetros: limite diário de 6 notificações, cooldown de 15 minutos, sem interrupção em horário DND (sugestões são preservadas, não descartadas), perfil com "não quero ser incomodado" reduz automaticamente a frequência — evita fadiga e evita "guardar rancor"

🔔 Fala mesmo com o terminal fechado: daemon + notificação de desktop

proactive-mcp daemon --install com um clique para ficar residente (auto-início via launchd/systemd): mesmo sem abrir nenhum agente, ele verifica sugestões pendentes e fala proativamente via notificação de desktop (Central de Notificações do macOS / bandeja do Windows / notify-send do Linux); clicar na notificação abre o painel central proativo, e um clique aceita e transforma em tarefa.

🔄 Memória não fica presa: interoperabilidade UMP

proactive-mcp ump-export exporta para arquivo padrão Universal Memory Protocol, carregável e recuperável pelo SDK oficial UMP — a memória é seu ativo, e você pode migrar para qualquer ecossistema UMP quando quiser.

🛡️ Design anti-envenenamento, segurança de memória com limite

Memória extraída automaticamente fica como pending (aguardando confirmação) por padrão; só entra na recuperação após sua confirmação — bloqueia injeção de conteúdo malicioso/errado
Configuração de LLM com princípio de mesma origem: apiKey define a fonte de confiança, nunca mistura origens diferentes, evita roubo de chave
Cada memória/correção pode ser visualizada, confirmada, rejeitada e excluída por você

🔌 Plug and play, um MCP para todos

Protocolo MCP padrão (stdio), zero alteração de código para montar em qualquer agente compatível com MCP. Já validado em três hosts completamente diferentes: Claude Code, Kimi Code e Proma (12/08: Kimi também oferece instalação via plugin com um comando); disponível no Smithery: npx -y smithery mcp add 1797650355/proactive-agent.

Início rápido (< 1 minuto, sem necessidade de clone)

✅ Publicado no npm! Um comando resolve.

Método A (recomendado): instalação direta via npm

# 一条命令版（免安装，直接从 npm 拉取，适合快速体验）
npx -y @proactive-agent/mcp init

# 或安装后使用（本地 bin）
npm install @proactive-agent/mcp
npx proactive-mcp init

Basta node >= 18. init gerará um .mcp.json apontando para sua instalação local, zero dependências extras.

Ou monte manualmente (sem instalar pacote, puxando direto com npx):

# Claude Code
claude mcp add proactive-agent -- npx -y @proactive-agent/mcp

Método B (usuários de Kimi Code, um comando):

/plugins install https://github.com/ConradLu2740/ProactiveAgent/releases/latest/download/kimi-plugin.zip
/reload

Após instalar, sessões kimi comuns ganham memória proativa automaticamente (sem precisar de --agent); também é possível usar kimi --agent proactive para ativar o modo agressivo. Veja o Guia de uso do Kimi Code.

Método C: clone do repositório (desenvolvimento / personalização)

git clone https://github.com/ConradLu2740/ProactiveAgent.git && cd ProactiveAgent
npm install
npm run start:mcp

⚠️ Após iniciar o npm run start:mcp, o terminal permanecerá em execução — isso é o estado normal de bloqueio do servidor MCP (aguardando conexão do agente), não é travamento; mantenha-o em execução e abra seu agente para conectar.

Método D: inicie um painel central proativo local

# 免安装 / 已安装均可
npx -y @proactive-agent/mcp --today
# 打开 http://127.0.0.1:8737/today —— 建议、场景、画像、统计一目了然

(Também disponível com npm run start:today ao desenvolver com clone do repositório)

主动中心面板

Painel central proativo: sugestões pendentes + cenários em destaque + estatísticas de memória + perfil do usuário (atualização automática a cada 15s)

Valide imediatamente após montar (cerca de 1 minuto):

Abra o Claude Code (ou o agente que você usa; usuários de Kimi podem usar init --kimi) e inicie uma sessão
Digite: 以后提交代码前必须先写单元测试 → Você deve receber a sugestão "Gravar esta regra na memória de longo prazo?" (suggest_now)
Depois digite: 我偏好用 TypeScript 和 Bun e então pergunte: 我之前的偏好是什么？ → Conseguir recuperar a memória anterior = memória já funciona entre ferramentas

Não funcionou? proactive-mcp doctor faz diagnóstico com um clique.

Tabela rápida de requisitos de LLM

Recurso	Precisa de chave LLM?	Descrição
`memory_capture` / `memory_recall` / `persona_` / `scene_summary` / `suggest_` / `daily_review` / `onboarding_guide`	Não	Regras determinísticas puramente locais, funcionam direto
`memory_extract`	Opcional	Configure `MEMORY_LLM_*` para extração via LLM (padrão compatível com DeepSeek); sem configuração, degrada automaticamente para modo de regras, zero envio externo
`memory_recall` reescrita de sinônimos	Aprimoramento opcional	Com LLM configurado, adiciona automaticamente recuperação por sinônimos; sem configuração, usa sinônimos por regras como fallback

Exemplo de configuração opcional (necessário apenas para memory_extract):

# ~/.proma-proactive/.env（或项目 .env，建议 chmod 600）
MEMORY_LLM_API_KEY=sk-xxx
MEMORY_LLM_BASE_URL=https://api.deepseek.com/v1
MEMORY_LLM_MODEL=deepseek-chat

Diferenças de configuração por host

Host	Geração automática de init	Mecanismo de push proativo	Passos manuais extras
Claude Code	`.mcp.json` + hooks `.claude/settings.json`	Hooks em três camadas (SessionStart / UserPromptSubmit / Stop)	Nenhum (TUI interativo funciona; `claude -p` requer `--allowedTools`)
Kimi Code	`.mcp.json` + `~/.kimi-code/mcp.json` + `agents/proactive.md` (requer `init --kimi`)	Direcionado por prompt (`kimi --agent proactive`)	Requer login/API key do Kimi; use um ou outro com kimi-plugin
Cursor	`.mcp.json`	Mapeamento oficial dos hooks do Claude	Confirme que .mcp.json foi reconhecido; ative compatibilidade de hooks de terceiros*
Cline	`.mcp.json`	Manual	Conecte `event-capture.js` manualmente (opcional)*
Codex	`.mcp.json`	Manual	Conecte `event-capture.js` manualmente (opcional)*

* O repositório testou apenas Claude Code / Kimi Code / Proma; itens de Cursor / Cline / Codex seguem a documentação oficial.

Visão geral de capacidades

Tools (20, disponíveis em qualquer host)

Categoria	Ferramenta	O que faz
🧠 Gravação de memória	`memory_capture`	Grava explicitamente um item (preferência/fato/correção/fluxo, efeito imediato; suporta scope: project/global)
🧠 Extração de memória	`memory_extract`	Entrega a conversa ao mecanismo para extração automática (padrão aguardando confirmação, anti-envenenamento)
🔍 Recuperação de memória	`memory_recall`	Recuperação por palavras-chave/híbrida, injeta contexto antes de iniciar tarefas (padrão auto: projeto + global combinados)
✅ Fechamento de memória	`memory_pending` / `memory_confirm` / `memory_reject` / `correction_confirm` / `correction_reject`	Confirmação/rejeição de memórias pendentes + correções de comportamento
👤 Perfil	`persona_get` / `persona_save`	Lê perfil combinado (base global + sobreposição de projeto) / salva perfil manualmente
🔥 Cenários	`scene_summary`	Cenários recentes em destaque ("no que você tem trabalhado")
📊 Estatísticas	`memory_stats`	Estatísticas do sistema de memória (inclui dinâmica: mudanças de hoje / dias desde última atualização / convite para revisão a cada 3 dias)
💡 Sugestões	`suggest_now` / `suggest_list` / `suggest_accept` / `suggest_ignore`	Avaliação de sugestões proativas + ciclo de feedback (aprendizado de frequência)
🃏 Cartão unificado	`card_list` / `card_get`	Visão de protocolo unificado ActionCard entre fontes (fonte atual: suggestion; futuro: agent/automation/bridge)
📋 Modelos	`daily_review` / `onboarding_guide`	Revisão diária / instruções de uso

Resources & Prompts

memory://today — sugestões de hoje + cenários em destaque
memory://stats、memory://persona
Prompts: daily_review (revisão diária)、onboarding (guia de inicialização a frio)

Capacidades adicionais

Manutenção de memória (0.8.0, alinhado à governança de memória do Proma v0.17.0): memory_stats exibe "X mudanças hoje · N dias desde última atualização"; quando a memória não é atualizada há mais de 3 dias, retorna convite para revisão (limpar memórias desatualizadas, confirmar itens pendentes, reorganizar perfil se necessário); persona_get avisa para simplificar/reorganizar quando o perfil está sobrecarregado (>45 linhas / >6 seções); onboarding_guide oferece guia em duas etapas "criar perfil primeiro → depois adicionar evidências".
Painel Web /today: central proativa local (atualização automática a cada 15s), qualquer host pode abrir no navegador; POST /api/evaluate permite que o host envie mensagens recentes para acionar avaliação durante a sessão; cartões de sugestão suportam feedback com um clique "Aceitar / Ignorar" (ciclo fechado ActionCard, aceitar já cria tarefa local)
Daemon (0.5.0, saída proativa): proactive-mcp daemon fica residente em segundo plano, verifica sugestões pendentes e fala proativamente via notificação de desktop (Central de Notificações do macOS / balão da bandeja do Windows / notify-send do Linux); clicar na notificação abre o painel central proativo; --install configura auto-início com um clique (launchd / systemd); --status / --stop gerenciam; doctor inclui verificação de saúde do daemon e estado de fadiga de hoje (notificados/limite). Intervalo de verificação PROACTIVE_DAEMON_INTERVAL_MIN (padrão 60 minutos), no máximo 1 notificação por vez, sem repetir a mesma notificação, sem interromper em horário DND e sem descartar sugestões (princípio da moderação).
Controle de fadiga de notificações (0.8.0): limite diário de notificações (padrão 6/dia, sobrescrito por PROACTIVE_DAEMON_DAILY_LIMIT, reset automático entre dias) + janela de cooldown (padrão 15 minutos, sobrescrito por PROACTIVE_DAEMON_COOLDOWN_MIN) + coeficiente de perturbação orientado por perfil — quando o perfil contém regras como "não perturbe/silêncio", o limite cai pela metade e o cooldown dobra (respeita a expressão "não quero ser incomodado" do usuário); ao atingir limite/cooldown, sugestões são preservadas, não descartadas, e continuam no dia seguinte
Rede de percepção entre ferramentas (0.6.0): protocolo de eventos unificado — hooks de cada ferramenta normalizam eventos de sessão/mensagem/commit e gravam em ~/.proma-proactive/events/ (somente o usuário atual pode ler/escrever); o daemon lê eventos recentes durante a verificação e constrói messages para avaliação verdadeiramente agendada (conclui o pendente P0-1 do 0.5); hooks do Claude Code / Kimi Code já gravam eventos inline; Cursor suporta oficialmente carregar hooks do Claude Code para integração automática; Codex/Cline podem usar dist/hooks/event-capture.js como entrada genérica; init imprime guia de integração entre ferramentas; guia para terceiros em docs/developers/adapter-guide.md
Interoperabilidade UMP (0.7.0 L0): proactive-mcp ump-export exporta memória para arquivo Universal Memory Protocol (.ump/memory.ump.json), ump-import importa de arquivo UMP (padrão aguardando confirmação, anti-envenenamento) — qualquer cliente UMP pode ler/escrever memória do ProactiveAgent; avaliação de compatibilidade na documentação .context, ponte L2 MCP store aguardando ecossistema maduro
Hooks do Claude Code (três camadas):
- SessionStart (today-push): no início da sessão, envia sugestões pendentes + cenários em destaque
- UserPromptSubmit (user-prompt): avaliação em tempo real durante a sessão — se você disser "use pnpm daqui em diante", recebe imediatamente sugestão de correção; sinais fracos silenciam automaticamente
- Stop (session-end): consolida memória e avalia sugestões ao final da sessão
⚠️ Limitação do modo não interativo: hooks só disparam em sessões TUI interativas do Claude Code; scripts claude -p / modo CI não disparam hooks. Em cenários de script, use claude -p --allowedTools "mcp__proactive-agent__*" para autorizar explicitamente as ferramentas MCP e deixe o modelo chamar diretamente suggest_now / memory_capture (atenção: --permission-mode acceptEdits não concede permissão às ferramentas MCP; é necessário --allowedTools explícito).
Hooks do Kimi Code (transmissão proativa): UserPromptSubmit gera XML <notification> alinhado ao padrão de notificação de tarefas do Kimi — o modelo Kimi, ao ver a notificação, transmite proativamente a sugestão ao usuário ("você disse X antes, quer que eu lembre?"), reutilizando o canal externalHooks do Kimi.

⚠️ Pré-requisito: Kimi Code precisa de login concluído ou API key configurada (kimi na primeira execução de /login, ou configure [providers.<name>] + api_key conforme config.toml). Sem configuração, kimi -p reporta No model configured. Diagnóstico: kimi doctor / kimi provider list. A configuração de hooks do Kimi é TOML (não JSON), escrita em ~/.kimi-code/config.toml:
```
[[hooks]]
event = "UserPromptSubmit"
command = "node <mcp 安装路径>/dist/hooks/kimi-user-prompt.js"
timeout = 10
```
Campos permitidos: apenas event / matcher / command / timeout; UserPromptSubmit dispara quando o usuário envia mensagem, stdout do hook é anexado ao contexto, e o modelo transmite proativamente ao ver <notification>.

Casos de uso

Cenário 1: memória de longo prazo compartilhada entre ferramentas

今天：在 Claude Code 里说"我偏好用 TypeScript"
明天：打开 Kimi Code 写代码，它自动 recall 到你的偏好，直接按你的习惯来

Cenário 2: da "correção" ao "nunca mais repetir"

你说："以后提交前先写单元测试"
→ suggest_now 识别为 correction 建议
→ 你点"接受"：规则写入记忆 + 回流用户画像
→ 以后所有 agent 都遵守这条规则

Cenário 3: sugestões proativas durante a sessão (0.5.0)

你在 Claude Code 里输入："以后提交前先跑测试"
→ UserPromptSubmit hook 实时评估（evaluateNow, session_mid）
→ 建议注入当前会话："记住这个纠正？接受：suggest_accept"
→ 接受后规则写入记忆，所有宿主下次遵守

Cenário 4: sugestões de tarefas agendadas com percepção de tempo (0.5.0)

你说："每天下午5点帮我检查发布状态"
→ 时间解析器识别周期 → cron: 0 17 * * *
→ 建议预填真实 cron，接受后直接建好定时任务

Cenário 5: daemon proativo sem supervisão (0.5.0)

proactive-mcp daemon --install   # 安装登录自启（macOS/Linux）
→ 每隔 60 分钟巡检待处理建议
→ 有值得开口的建议时，桌面通知弹出来（点击打开主动中心）
→ 在面板点「接受」→ automation/todo 建议直接落地为本地任务
→ 该沉默时沉默：无新建议 / DND 时段（建议保留不吞） / 同条建议不重复打扰

Arquitetura

flowchart LR
    A[Claude Code] -->|MCP stdio| S[proactive-mcp]
    B[Kimi Code] -->|MCP stdio| S
    C[Cline / Cursor] -->|MCP stdio| S
    D[Proma 应用] -->|dogfooding| E[proactive-core]
    S --> E[proactive-core 引擎]
    E --> F[(~/.proma-proactive 记忆)]

@proactive-agent/core: mecanismo headless (memória + sugestões), zero dependências em tempo de execução, consumível por qualquer host
@proactive-agent/mcp: camada de wrapper do MCP Server (tools/resources/prompts + painel + hooks)

Modelo de memória em camadas

L1 Atom    结构化记忆条目（LLM 提取 + 去重 + 优先级）
L2 Scene   场景块（近期主题聚合，主动性时机信号）
L3 Persona 用户画像 markdown（稳定偏好，带来源溯源）
Correction 行为纠正候选（需确认后生效）

Segurança e privacidade

Design	Descrição
Pending por padrão	Memória extraída automaticamente precisa de confirmação para entrar na recuperação, bloqueando cadeia de envenenamento
Princípio de mesma origem no LLM	apiKey define a fonte principal de confiança; baseUrl/model só vêm da mesma origem; baseUrl apenas https
Dados locais primeiro	Memória fica na máquina local em `~/.proma-proactive/`, sem sincronização em nuvem
Controle do usuário	Cada memória/correção pode ser confirmada, rejeitada, excluída e limpa
Horário de não perturbar	DND (padrão 22:30-08:00) não gera novas sugestões
Princípio da moderação	Máximo 1 sugestão por vez, orçamento por sessão, "silêncio quando deve silenciar"

FAQ

P: Quais agentes são suportados? R: Qualquer agente compatível com MCP: Claude Code, Kimi Code, Cline, Cursor, Windsurf, VS Code, etc. Proma é nativo (dogfooding).

P: Onde a memória fica armazenada? R: Padrão em ~/.proma-proactive/, sobrescrevível com PROACTIVE_DATA_DIR. Arquivos puramente locais (JSONL/markdown), com backup/migração a qualquer momento.

P: Preciso de API key? R: As funcionalidades principais (memory_capture / memory_recall / suggest_* etc.) não precisam, funcionam direto localmente; apenas a extração via LLM em memory_extract é opcional. Veja a "Tabela rápida de requisitos de LLM" no início rápido.

P: Qual a diferença para outras soluções de memória? R: A maioria é "memória passiva de ferramenta única". ProactiveAgent é compartilhamento entre ferramentas + sugestões proativas — ensine uma vez, use em qualquer lugar, e fale proativamente apenas no momento certo.

P: Minhas conversas são enviadas para fora? R: Apenas o modo LLM de memory_extract envia o trecho atual da conversa para o LLM que você mesmo configurou (padrão compatível com DeepSeek); o modo de regras tem zero envio externo. Capture/recall explícitos são puramente locais.

P: O desempenho piora com muitas memórias? R: Desde 0.5.4, memory_recall usa índice invertido (term → atoms, com cache + invalidação automática + fail-open), escaneando apenas o conjunto candidato com termos da consulta, em vez de varredura completa — imperceptível em projetos pessoais/médios, mantendo baixa latência mesmo com dezenas de milhares de memórias. Também recomendamos observar o tamanho da memória regularmente com proactive-mcp stats e usar proactive-mcp archive para arquivamento com TTL.

Roadmap

Contribuição

PRs / Issues são bem-vindos! Ambiente de desenvolvimento: Node 22 + TypeScript + Vitest + esbuild. npm install && npm test && npm run build

Licença

MIT