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 todos os lugares. Faça Claude Code / Kimi Code / Cline / Cursor / Proma compartilharem a mesma «memória proativa» — ela não apenas lembra tudo o que você ensinou, mas também fala proativamente nos momentos certos para lembrá-lo. Com um único MCP montado, todos os agentes ganham capacidade proativa imediatamente.

Diferente de outras ferramentas de memória que «apenas registram»: ProactiveAgent registra e também fala proativamente quando acha que deve lembrá-lo — 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 é saída real de execução de 2026-08-05, não uma animação de demonstração: Claude Code grava memória → Kimi Code recupera diretamente (100% de precisão); correção de comportamento / necessidades periódicas → sugestões proativas acertam e são aceitas.

👉 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 real
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 fazer commit daqui em diante» → `suggest_now` reconhece 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` reconhece sugestão de automação → aceita e entra no agendamento
Integração Kimi com um comando (testado em 8/12)	`/plugins install .../kimi-plugin.zip` → sessões comuns `kimi` ganham memória proativa automaticamente (o modelo captura ativamente seguindo as instruções do plugin → recall em novas sessões com precisão, sem precisar de `--agent`)
Kimi proativo em três vias (testado em 8/12)	Com hooks restaurados, fluxo completo: injeção de sugestões/perfil no início da sessão (today-push) → transmissão de sinais fortes durante o processo `<notification>` (kimi-user-prompt) → sedimentação automática de memória no encerramento (kimi-session-end, aguardando confirmação por padrão)
Interoperabilidade UMP (testado em 8/12)	`ump-export` exporta → o `@universalmemoryprotocol/core` oficial carrega 5/5 + recall (scope.owner) com 100% de precisão — a memória não fica presa a nenhuma ferramenta

Por que vale a pena usar

🎯 A memória é um «ativo do usuário», não um «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 no ~/.proma-proactive/, e todos os agentes leem e gravam a mesma memória através do mesmo servidor MCP.

Esqueça o «preciso ensinar de novo em cada ferramenta»: ensine uma vez as preferências de TypeScript e todos os agentes lembrarão.

💡 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 → sugestão de gravar a regra na memória de longo prazo (prevenir recorrência)
Você repete a mesma ação → sugestão de automação / sedimentar como fluxo
Conversa casual, recusas, horários de descanso → silêncio (isso é uma capacidade)
A moderação tem parâmetros: limite diário de 6 notificações, cooldown de 15 minutos, sem interrupções em horários DND (sugestões são preservadas, não engolidas); se o perfil mencionar «não quero ser incomodado», a frequência cai automaticamente — previne fadiga e também previne «guardar rancor»

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

proactive-mcp daemon --install fica residente com um clique (auto-inicialização via launchd/systemd): mesmo sem nenhum agente aberto, ele inspeciona sugestões pendentes e fala proativamente via notificações de desktop (Central de Notificações do macOS / bandeja do Windows / notify-send do Linux); clicar na notificação abre o painel do centro ativo, e com um clique a sugestão é aceita e vira tarefa.

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

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

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

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

🔌 Plug and play, um MCP para tudo

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

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

✅ Publicado no npm! Resolva com um comando.

Opção A (recomendada): instalação direta via npm

# 在你自己的项目里（或任意目录）
npm install @proactive-agent/mcp

# 一键生成挂载配置（Claude Code / Kimi Code / Cline / Cursor 通用）
npx proactive-mcp init

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

Ou monte manualmente (sem instalar pacote, usando direto o bundle do GitHub Release):

# Claude Code
claude mcp add proactive-agent -- node <repo>/dist-publish/mcp/dist/index.js

Opção B (usuários Kimi Code, um comando):

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

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


**方式 C：clone 仓库（开发 / 自定义）**
```bash
git clone https://github.com/ConradLu2740/ProactiveAgent.git && cd ProactiveAgent
npm install
npm run start:mcp

Opção D: suba um painel local do centro ativo

npm run start:today
# 打开 http://127.0.0.1:8737/today —— 建议、场景、画像、统计一目了然

主动中心面板

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

Teste imediatamente após montar:

agent: 以后提交代码前必须先写单元测试再提交
→ agent 建议把这条规则写入长期记忆（memory_extract / suggest_now）
agent: 我偏好用 TypeScript 和 Bun
→ agent 调用 memory_capture 记住（下次任何工具都记得）

Visão geral das capacidades

Tools (20, disponíveis em qualquer host)

Categoria	Ferramenta	O que faz
🧠 Gravação de memória	`memory_capture`	Registra explicitamente uma memória (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 (aguardando confirmação por padrão, anti-envenenamento)
🔍 Recuperação de memória	`memory_recall`	Busca por palavra-chave/híbrida, injeta contexto antes de iniciar a tarefa (padrão auto: projeto + global combinados)
✅ Ciclo de fechamento de memória	`memory_pending` / `confirm` / `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 do projeto) / salva perfil manualmente
🔥 Cenários	`scene_summary`	Cenários recentes em destaque («no que você tem trabalhado ultimamente»)
📊 Estatísticas	`memory_stats`	Estatísticas do sistema de memória (incluindo dinâmica de memória: mudanças de hoje / dias desde a última atualização / convite de revisão de 3 dias)
💡 Sugestões	`suggest_now` / `list` / `accept` / `ignore`	Avaliação de sugestões proativas + ciclo de feedback (aprendizado de frequência)
🃏 Card unificado	`card_list` / `card_get`	Visão de protocolo ActionCard unificado entre fontes (fonte atual: suggestion; futuramente entrega de agent/automation/bridge)
📋 Templates	`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 (orientação de cold start)

Capacidades adicionais

Manutenção de memória (0.8.0, alinhado com a governança de memória do Proma v0.17.0): memory_stats exibe «X mudanças hoje · N dias desde a última atualização»; quando a memória fica mais de 3 dias sem atualização, retorna convite de revisão (limpar memórias obsoletas, confirmar itens pendentes, reorganizar o perfil se necessário); persona_get sugere compactação/reorganização quando o perfil está sobrecarregado (>45 linhas / >6 seções); onboarding_guide fornece orientação em duas fases «primeiro crie o perfil → depois adicione evidências».
Painel Web /today: centro ativo 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 disparar avaliação durante a sessão; cards de sugestão suportam feedback de 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, inspeciona sugestões pendentes e fala proativamente via notificações 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 do centro ativo; --install configura auto-inicialização ao logar 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 inspeção PROACTIVE_DAEMON_INTERVAL_MIN (padrão 60 minutos), no máximo 1 notificação por vez, mesma notificação não se repete, DND não interrompe e não engole 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 no novo dia) + janela de cooldown (padrão 15 minutos, sobrescrito por PROACTIVE_DAEMON_COOLDOWN_MIN) + coeficiente de interrupção guiado pelo perfil — quando o perfil contém regras como «não me incomode / silêncio», o limite cai pela metade e o cooldown dobra (respeitando a expressão do usuário «não quero ser incomodado»); quando o limite/cooldown é atingido, as sugestões são preservadas, não engolidas 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 no ~/.proma-proactive/events/ (somente o usuário atual pode ler/gravar); o daemon lê eventos recentes na inspeção e constrói mensagens para avaliação realmente agendada (completa o residual P0-1 do 0.5); hooks do Claude Code / Kimi Code já gravam eventos inline, o Cursor suporta oficialmente carregar hooks do Claude Code para integração automática, Codex/Cline podem usar a entrada genérica dist/hooks/event-capture.js; init imprime o 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órias como arquivo Universal Memory Protocol (.ump/memory.ump.json), ump-import importa de arquivo UMP (aguardando confirmação por padrão, anti-envenenamento) — qualquer cliente UMP pode ler/gravar memórias do ProactiveAgent; avaliação de compatibilidade nos documentos .context, bridge L2 MCP store aguardando o ecossistema amadurecer
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 a sugestão de correção; sinais fracos ficam silenciosos automaticamente
- Stop (session-end): no fim da sessão, sedimenta memórias + avalia sugestões
⚠️ Limitação em modo não interativo: os hooks disparam apenas em sessões interativas TUI do Claude Code; claude -p script/modo CI não dispara hooks. Em cenários de script, use claude -p --allowedTools "mcp__proactive-agent__*" para autorizar explicitamente as ferramentas MCP e depois deixe o modelo chamar diretamente suggest_now / memory_capture (atenção: --permission-mode acceptEdits não concede permissão às ferramentas MCP; é obrigatório --allowedTools explicitamente).
Hooks do Kimi Code (transmissão proativa): UserPromptSubmit gera <notification> XML alinhado ao padrão de notificação de tarefas do Kimi — quando o modelo Kimi vê a notificação, ele transmite proativamente a sugestão ao usuário («você disse X da última vez, quer que eu lembre?»), reutilizando o canal externalHooks do Kimi.

⚠️ Pré-requisito: o Kimi Code precisa primeiro completar o login ou configurar a API key (kimi na primeira execução /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, o 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: de «correção» a «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órias extraídas automaticamente precisam de confirmação para entrar no recall, bloqueando cadeia de envenenamento
Princípio de mesma origem LLM	apiKey define a fonte de confiança principal; baseUrl/model vêm apenas da mesma origem; baseUrl apenas https
Dados locais primeiro	Memórias ficam no `~/.proma-proactive/` da máquina local, sem sincronização em nuvem
Controle do usuário	Cada memória/correção pode ser confirmada, rejeitada, excluída ou limpa
Horário de não perturbação	DND (padrão 22:30-08:00) não gera novas sugestões
Princípio da moderação	No máximo 1 sugestão por vez, orçamento limitado 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: Por padrão em ~/.proma-proactive/, sobrescrito por PROACTIVE_DATA_DIR. Arquivos puramente locais (JSONL/markdown), com backup/migração a qualquer momento.

P: Preciso de API key? R: Gravação de memória memory_capture e recuperação memory_recall não precisam. A extração via LLM do memory_extract é opcional (configure a variável de ambiente MEMORY_LLM_*); sem configuração, degrada automaticamente para modo de regras (zero envio externo).

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 e use em todos os lugares, falando proativamente apenas nos momentos apropriados.

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

P: O desempenho fica lento com grande volume de memória? R: Desde o 0.5.4, memory_recall usa índice invertido (term → atoms, com cache + invalidação automática + fail-open), escaneando apenas o conjunto candidato que contém os termos da consulta, em vez de varredura completa — imperceptível para projetos pessoais/médios, mantém baixa latência mesmo com dezenas de milhares de memórias. Recomenda-se também usar proactive-mcp stats periodicamente para observar o tamanho da memória e proactive-mcp archive para governança de arquivamento por 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

License

MIT