ProactiveAgent

Memoria proactiva y sugerencias entre herramientas para Claude Code, Kimi Code, Cline, Cursor. Aprende una vez, usa en todas partes.

GitHub

Prueba este MCPPatrocinado

Documentación

ProactiveAgent 🧠

Enseña una vez, úsalo en todas partes. Permite que Claude Code / Kimi Code / Cline / Cursor / Proma compartan la misma «memoria proactiva»: no solo recuerda todo lo que le has enseñado, sino que además toma la iniciativa de recordártelo en el momento adecuado. Con un solo MCP montado, todos los agentes obtienen capacidad proactiva al instante.

A diferencia de otras herramientas de memoria que «solo recuerdan»: ProactiveAgent recuerda y también toma la iniciativa de hablar cuando cree que debe recordártelo: correcciones, seguimientos, automatizaciones, tareas pendientes y habilidades, cinco tipos de sugerencias proactivas.

中文 · English

🎬 Historia de validación (entiende en 30 segundos qué hace)

Todo el contenido es salida real de ejecución del 2026-08-05, no una animación de demostración: Claude Code escribe memoria → Kimi Code la recupera directamente (100% de acierto); corrección de comportamiento / necesidades periódicas → sugerencia proactiva acertada y aceptada.

👉 Abre la página de demostración interactiva: Demo en línea (GitHub Pages) (ábrela directamente en el navegador)

⚠️ La página blob de GitHub es solo un visor de código y no ejecuta scripts HTML; usa el enlace de Pages de arriba para ver la demo interactiva.

Escenario	Resultado real
Compartir entre herramientas	Claude Code `memory_capture` escribe → Kimi Code `memory_recall` recupera con acierto (relevancia 100%, cero configuración)
Sugerencia proactiva: corrección	«A partir de ahora escribe pruebas unitarias antes de hacer commit» → `suggest_now` identifica sugerencia de corrección → `suggest_accept` acepta → retroalimentación de vuelta
Sugerencia proactiva: automatización	«Revisa el progreso del proyecto todos los días a las 5 p. m.» → `suggest_now` identifica sugerencia de automatización → acepta y entra en programación
Kimi se integra con un solo comando (probado el 8/12)	`/plugins install .../kimi-plugin.zip` → las sesiones normales de `kimi` obtienen memoria proactiva automáticamente (el modelo captura activamente según las instrucciones del plugin → la nueva sesión recupera con acierto, sin necesidad de `--agent`)
Kimi proactividad en tres vías (probado el 8/12)	Tras restaurar hooks, cadena completa: al inicio de sesión se inyectan sugerencias/perfil (today-push) → señales fuertes del proceso `<notification>` se transmiten (kimi-user-prompt) → al final se sedimenta memoria automáticamente (kimi-session-end, pendiente de confirmación por defecto)
Interoperabilidad UMP (probado el 8/12)	`ump-export` exporta → el `@universalmemoryprotocol/core` oficial carga 5/5 + recall (scope.owner) todo con acierto: la memoria no queda bloqueada por ninguna herramienta

Por qué vale la pena usarlo

🎯 La memoria es un «activo de usuario», no un «activo de herramienta»

Las preferencias que le enseñas en Claude Code se aplican automáticamente en Kimi Code y Cline, porque la memoria vive en ~/.proma-proactive/ y todos los agentes leen y escriben la misma memoria a través del mismo servidor MCP.

Dile adiós a «tener que reenseñar en cada herramienta»: enseña una vez las preferencias de TypeScript y todos los agentes lo recordarán.

💡 Habla con iniciativa: silencio cuando debe callar

No es un push parlanchín, sino que solo habla cuando hay señal, con moderación parametrizada:

Corriges al agente → sugiere escribir la regla en la memoria a largo plazo (para evitar que se repita)
Repites la misma acción → sugiere automatizarla / convertirla en flujo
Charla casual, rechazos, horarios de molestia → silencio (eso es capacidad)
La moderación tiene parámetros: límite diario de 6 notificaciones, enfriamiento de 15 minutos, sin molestias en horario DND (las sugerencias se conservan, no se descartan), y si el perfil dice «no quiero que me molesten», se reduce la frecuencia automáticamente: evita la fatiga y también el «guardar rencor»

🔔 Habla incluso con la terminal cerrada: proceso guardián + notificaciones de escritorio

proactive-mcp daemon --install se queda residente con un clic (autoarranque con launchd/systemd): incluso si no tienes ningún agente abierto, inspecciona sugerencias pendientes y habla proactivamente mediante notificaciones de escritorio (Centro de notificaciones de macOS / bandeja de Windows / notify-send de Linux); al hacer clic en la notificación se abre el panel del centro proactivo y con un clic se acepta y se materializa la tarea.

🔄 La memoria no queda bloqueada: interoperabilidad UMP

proactive-mcp ump-export exporta a un archivo estándar de Universal Memory Protocol, cargable y recuperable con el SDK oficial de UMP: la memoria es tu activo y puedes llevarla a cualquier ecosistema UMP cuando quieras.

🛡️ Diseño antienvenenamiento, seguridad de memoria con límites

La memoria extraída automáticamente queda pendiente (pending) por defecto; solo entra en recuperación cuando la confirmas: bloquea la inyección de contenido malicioso o erróneo
Configuración de LLM con principio de misma fuente: apiKey determina la fuente de confianza, nunca se mezclan fuentes cruzadas, evita el secuestro de claves
Cada memoria/corrección puedes verla, confirmarla, rechazarla y eliminarla

🔌 Plug and play, un MCP para todo

Protocolo MCP estándar (stdio), cero cambios de código para montarlo en cualquier agente compatible con MCP. Ya verificado de forma real en Claude Code, Kimi Code y Proma, tres hosts completamente distintos (8/12: Kimi además ofrece un comando de instalación de plugin); disponible en Smithery: npx -y smithery mcp add 1797650355/proactive-agent.

Inicio rápido (< 1 minuto, sin necesidad de clonar)

✅ ¡Ya publicado en npm! Un solo comando y listo.

Opción A (recomendada): instalación directa con npm

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

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

Solo necesitas node >= 18. init generará un .mcp.json que apunta a tu instalación local, cero dependencias adicionales.

O montaje manual (sin instalar paquete, usando directamente el bundle de GitHub Release):

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

Opción B (usuarios de Kimi Code, un solo comando):

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

Tras instalar, las sesiones normales de kimi obtienen memoria proactiva automáticamente (sin necesidad de --agent); además puedes kimi --agent proactive para activar el modo agresivo. Consulta la Guía de uso de Kimi Code.


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

Opción D: inicia un panel local del centro proactivo

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

主动中心面板

Panel del centro proactivo: sugerencias pendientes + escenarios destacados + estadísticas de memoria + perfil de usuario (auto-refresco cada 15 s)

Pruébalo inmediatamente tras montarlo:

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

Resumen de capacidades

Tools (20, disponibles en cualquier host)

Categoría	Herramienta	Qué hace
🧠 Escritura de memoria	`memory_capture`	Recuerda explícitamente una (preferencia/hecho/corrección/flujo, efecto inmediato; admite scope: project/global)
🧠 Extracción de memoria	`memory_extract`	Entrega la conversación al motor para extracción automática (pendiente de confirmación por defecto, antienvenenamiento)
🔍 Recuperación de memoria	`memory_recall`	Búsqueda por palabras clave/híbrida, inyecta contexto antes de empezar la tarea (por defecto auto: proyecto + global combinados)
✅ Cierre de memoria	`memory_pending` / `confirm` / `reject`	Confirmación/rechazo de memoria pendiente + correcciones de comportamiento
👤 Perfil	`persona_get` / `persona_save`	Lee el perfil combinado (base global + cobertura de proyecto) / guarda el perfil manualmente
🔥 Escenarios	`scene_summary`	Escenarios destacados recientes («¿en qué has estado trabajando últimamente?»)
📊 Estadísticas	`memory_stats`	Estadísticas del sistema de memoria (incluye dinámicas de memoria: cambios de hoy / días desde la última actualización / invitación a revisión de 3 días)
💡 Sugerencias	`suggest_now` / `list` / `accept` / `ignore`	Evaluación de sugerencias proactivas + bucle de retroalimentación (aprendizaje de frecuencia)
🃏 Tarjeta unificada	`card_list` / `card_get`	Vista de protocolo unificado ActionCard entre fuentes (fuente actual suggestion; en el futuro agent/automation/bridge)
📋 Plantillas	`daily_review` / `onboarding_guide`	Revisión diaria / instrucciones de uso

Resources y Prompts

memory://today — sugerencias de hoy + escenarios destacados
memory://stats、memory://persona
Prompts: daily_review (revisión diaria)、onboarding (guía de arranque en frío)

Capacidades adicionales

Mantenimiento de memoria (0.8.0, alineado con la gobernanza de memoria de Proma v0.17.0): memory_stats muestra «X cambios hoy · N días desde la última actualización»; si la memoria lleva más de 3 días sin actualizarse, devuelve una invitación a revisión (limpiar memoria obsoleta, confirmar pendientes, reorganizar el perfil si es necesario); persona_get avisa cuando el perfil está sobrecargado (>45 líneas / >6 secciones) para simplificarlo y reorganizarlo; onboarding_guide ofrece una guía en dos fases: «primero crear perfil → luego añadir evidencia».
Panel web /today: centro proactivo local (auto-refresco cada 15 s), cualquier host puede abrir el navegador para verlo; POST /api/evaluate permite que el host envíe los mensajes recientes para activar la evaluación en sesión; las tarjetas de sugerencia admiten retroalimentación de un clic «Aceptar / Ignorar» (cierre ActionCard, al aceptar se materializa como tarea local)
Proceso guardián (salida proactiva 0.5.0): proactive-mcp daemon residente en segundo plano, inspecciona sugerencias pendientes y habla proactivamente mediante notificaciones de escritorio (Centro de notificaciones de macOS / burbuja de bandeja de Windows / notify-send de Linux); al hacer clic en la notificación se abre el panel del centro proactivo; --install configura el autoarranque al iniciar sesión con un clic (launchd / systemd); --status / --stop gestión; doctor incluye comprobación de salud del daemon y estado de fatiga de hoy (notificadas/límite). Intervalo de inspección PROACTIVE_DAEMON_INTERVAL_MIN (por defecto 60 minutos), máximo 1 notificación por vez, la misma no se repite para no molestar, y en horario DND no molesta ni descarta sugerencias (credo de moderación).
Control de fatiga de notificaciones (0.8.0): límite diario de notificaciones (por defecto 6/día, PROACTIVE_DAEMON_DAILY_LIMIT lo sobrescribe, se reinicia automáticamente al cambiar de día) + ventana de enfriamiento (por defecto 15 minutos, PROACTIVE_DAEMON_COOLDOWN_MIN lo sobrescribe) + coeficiente de molestia impulsado por el perfil: si el perfil contiene reglas como «no molestar/silencio», el límite se reduce a la mitad y el enfriamiento se duplica (respeta la expresión del usuario de «no quiero que me molesten»); al alcanzar el límite/enfriamiento, las sugerencias se conservan, no se descartan, y continúan al día siguiente
Red de percepción entre herramientas (0.6.0): protocolo de eventos unificado: los hooks de cada herramienta normalizan los eventos de sesión/mensaje/commit y los escriben en ~/.proma-proactive/events/ (solo el usuario actual puede leer/escribir); el daemon lee los eventos recientes durante la inspección y construye mensajes para evaluación realmente programada (completa el pendiente P0-1 de 0.5); los hooks de Claude Code / Kimi Code ya escriben eventos en línea, Cursor admite oficialmente cargar los hooks de Claude Code para integrarse automáticamente, Codex/Cline pueden usar la entrada genérica dist/hooks/event-capture.js; init imprime la guía de integración entre herramientas; la guía para terceros está en docs/developers/adapter-guide.md
Interoperabilidad UMP (0.7.0 L0): proactive-mcp ump-export exporta la memoria como archivo Universal Memory Protocol (.ump/memory.ump.json), ump-import importa desde archivo UMP (pendiente de confirmación por defecto, antienvenenamiento): cualquier cliente UMP puede leer/escribir la memoria de ProactiveAgent; la evaluación de compatibilidad está en la documentación .context, el puente L2 MCP store espera a que el ecosistema madure
Hooks de Claude Code (tres capas):
- SessionStart (today-push): al inicio de sesión, envía sugerencias pendientes + escenarios destacados
- UserPromptSubmit (user-prompt): evaluación en tiempo real durante la sesión: si dices «a partir de ahora usa pnpm», recibes al instante una sugerencia de corrección; las señales débiles se silencian automáticamente
- Stop (session-end): al final de la sesión, sedimenta memoria + evalúa sugerencias
⚠️ Limitación del modo no interactivo: los hooks solo se activan en sesiones TUI interactivas de Claude Code; los scripts claude -p / modo CI no activan hooks. Para escenarios de script, usa claude -p --allowedTools "mcp__proactive-agent__*" para autorizar explícitamente las herramientas MCP y deja que el modelo llame directamente a suggest_now / memory_capture (nota: --permission-mode acceptEdits no otorga permisos de herramientas MCP; debes usar explícitamente --allowedTools).
Hooks de Kimi Code (transmisión proactiva): UserPromptSubmit genera XML <notification> alineado con el paradigma de notificaciones de tareas de Kimi: cuando el modelo de Kimi ve la notificación, transmite proactivamente la sugerencia al usuario («la última vez dijiste X, ¿quieres que lo recuerde?»), reutilizando el canal externalHooks de Kimi.

⚠️ Requisito previo: Kimi Code debe haber iniciado sesión o tener configurada una API key (kimi ejecuta /login la primera vez, o configura [providers.<name>] + api_key según config.toml). Si no está configurado, kimi -p mostrará No model configured. Diagnóstico: kimi doctor / kimi provider list. La configuración de hooks de Kimi es TOML (no JSON), se escribe en ~/.kimi-code/config.toml:
```
[[hooks]]
event = "UserPromptSubmit"
command = "node <mcp 安装路径>/dist/hooks/kimi-user-prompt.js"
timeout = 10
```
Los campos solo permiten event / matcher / command / timeout; UserPromptSubmit se activa cuando el usuario envía un mensaje, el stdout del hook se adjunta al contexto, y el modelo, al ver <notification>, transmite proactivamente.

Casos de uso

Caso 1: memoria a largo plazo compartida entre herramientas

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

Caso 2: de la «corrección» a «nunca más volver a fallar»

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

Caso 3: sugerencias proactivas durante la sesión (0.5.0)

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

Caso 4: sugerencias de tareas programadas con conciencia del tiempo (0.5.0)

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

Caso 5: proceso guardián proactivo sin supervisión (0.5.0)

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

Arquitectura

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: motor headless (memoria + sugerencias), cero dependencias en tiempo de ejecución, consumible por cualquier host
@proactive-agent/mcp: capa de envoltura del servidor MCP (tools/resources/prompts + panel + hooks)

Modelo de memoria por capas

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

Seguridad y privacidad

Diseño	Descripción
Pendiente por defecto	La memoria extraída automáticamente requiere confirmación antes de entrar en recuperación, bloquea la cadena de envenenamiento
Principio de misma fuente para LLM	apiKey determina la fuente principal de confianza; baseUrl/model solo se toman de la misma fuente; baseUrl solo https
Datos locales primero	La memoria vive en el `~/.proma-proactive/` local, sin sincronización en la nube
Control del usuario	Cada memoria/corrección se puede confirmar, rechazar, eliminar y vaciar
Horario sin molestias	DND (por defecto 22:30-08:00) no genera nuevas sugerencias
Principio de moderación	Máximo 1 sugerencia por vez, presupuesto limitado por sesión, «silencio cuando debe callar»

FAQ

P: ¿Qué agentes admite? R: Cualquier agente compatible con MCP: Claude Code, Kimi Code, Cline, Cursor, Windsurf, VS Code, etc. Proma nativo (dogfooding).

P: ¿Dónde se guarda la memoria? R: Por defecto en ~/.proma-proactive/, se puede sobrescribir con PROACTIVE_DATA_DIR. Archivos puramente locales (JSONL/markdown), se pueden respaldar/migrar en cualquier momento.

P: ¿Necesito una API key? R: La escritura de memoria memory_capture y la recuperación memory_recall no la necesitan. La extracción con LLM de memory_extract es opcional (configura la variable de entorno MEMORY_LLM_*); si no está configurada, se degrada automáticamente al modo de reglas (cero envíos externos).

P: ¿Qué diferencia hay con otras soluciones de memoria? R: La mayoría son «memoria pasiva de una sola herramienta». ProactiveAgent es compartida entre herramientas + sugerencias proactivas: enseña una vez y úsalo en todas partes, y solo habla proactivamente en el momento adecuado.

P: ¿Enviará mis conversaciones al exterior? R: Solo el modo LLM de memory_extract envía fragmentos de la conversación actual al LLM que tú mismo configures (por defecto interfaz compatible con DeepSeek); el modo de reglas tiene cero envíos externos. El capture/recall explícito es puramente local.

P: ¿El rendimiento se degrada con mucha memoria? R: Desde 0.5.4, memory_recall usa índice invertido (term → atoms, con caché + invalidación automática + fail-open), que solo escanea el conjunto candidato que contiene los términos de búsqueda, en lugar de un escaneo completo: imperceptible para proyectos personales/medianos, y mantiene baja latencia incluso con decenas de miles de memorias. Además, se recomienda usar periódicamente proactive-mcp stats para observar el tamaño de la memoria y proactive-mcp archive para la gobernanza de archivado por TTL.

Roadmap

Contribuciones

¡Bienvenidos PR / Issues! Entorno de desarrollo: Node 22 + TypeScript + Vitest + esbuild. npm install && npm test && npm run build

Licencia

MIT