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 🧠

Enséñalo 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 también toma la iniciativa de recordártelo en el momento adecuado. Con un solo montaje de MCP, todos los agentes obtienen capacidades proactivas 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 verificación (entiende lo que hace en 30 segundos)

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 precisión); corrección de comportamiento / necesidades periódicas → sugerencias proactivas que coinciden y se aceptan.

👉 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 demostración interactiva.

Escenario	Resultado real
Compartir entre herramientas	Claude Code `memory_capture` escribe → Kimi Code `memory_recall` recupera con precisión (relevancia 100%, cero configuración)
Sugerencia proactiva: corrección	«Escribe pruebas unitarias antes de cada commit» → `suggest_now` identifica sugerencia de corrección → `suggest_accept` acepta → retroalimentación de vuelta
Sugerencia proactiva: automatización	«Revisa el progreso del proyecto a las 5 p. m. todos los días» → `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 precisión, sin necesidad de `--agent`)
Kimi proactividad en tres vías (probado el 8/12)	Después de restaurar hooks, cadena completa: inicio de sesión inyecta sugerencias/perfil (today-push) → señales fuertes del proceso `<notification>` se transmiten (kimi-user-prompt) → al final se consolida 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) con precisión total — la memoria no queda bloqueada por ninguna herramienta

Por qué vale la pena usarlo

🎯 La memoria es un «activo a nivel de usuario», no un «activo a nivel 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 cada herramienta»: enseña una vez las preferencias de TypeScript y todos los agentes lo recordarán.

💡 Habla proactivamente: silencio cuando debe callar

No es un push parlanchín, sino hablar solo cuando hay señales, 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 / consolidarla como flujo
Charla casual, rechazos, horarios de no molestar → silencio (eso es capacidad)
La moderación tiene parámetros: límite diario de 6 notificaciones, enfriamiento de 15 minutos, sin interrupciones en horario DND (las sugerencias se conservan, no se descartan), si el perfil dice «no quiero que me molesten» se reduce la frecuencia automáticamente — previene la fatiga y también el «guardar rencor»

🔔 Habla incluso con la terminal cerrada: proceso daemon + notificaciones de escritorio

proactive-mcp daemon --install se mantiene residente con un clic (autoarranque con launchd/systemd): incluso si no tienes ningún agente abierto, inspecciona las 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 central 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, puedes llevarla a cualquier ecosistema UMP cuando quieras.

🛡️ Diseño anti-envenenamiento, 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/erróneo
Configuración de LLM con principio de misma fuente: apiKey determina la fuente de confianza, nunca se mezclan fuentes cruzadas, previene el secuestro de claves
Cada memoria/corrección puedes verla, confirmarla, rechazarla y eliminarla

🔌 Plug and play, un MCP para todos

Protocolo MCP estándar (stdio), cero cambios de código para montarlo en cualquier agente compatible con MCP. Ya verificado en Claude Code, Kimi Code y Proma, tres hosts completamente diferentes (8/12: Kimi también ofrece instalación por plugin con un comando); 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.

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

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

# 或安装后使用（本地 bin）
npm install @proactive-agent/mcp
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 el paquete, con npx directo):

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

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

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

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

Opción C: clonar el repositorio (desarrollo / personalización)

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

⚠️ Después de iniciar npm run start:mcp, la terminal se mantendrá en ejecución — este es el estado de bloqueo normal del servidor MCP (esperando conexión del agente), no es un cuelgue; mantenlo en ejecución y abre tu agente para conectarlo.

Opción D: iniciar un panel central proactivo local

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

(También puedes usar npm run start:today al clonar el repositorio para desarrollo)

主动中心面板

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

Verifica inmediatamente después del montaje (aprox. 1 minuto):

Abre Claude Code (o el agente que uses; los usuarios de Kimi pueden usar init --kimi) e inicia una sesión
Escribe: 以后提交代码前必须先写单元测试 → Deberías recibir la sugerencia «¿Guardar esta regla en la memoria a largo plazo?» (suggest_now)
Luego escribe: 我偏好用 TypeScript 和 Bun, y después pregunta: 我之前的偏好是什么？ → Si puede recuperar la memoria anterior = la memoria ya funciona entre herramientas

¿No funciona? proactive-mcp doctor diagnóstico con un clic.

Tabla rápida de requisitos de LLM

Función	¿Necesita clave de LLM?	Descripción
`memory_capture` / `memory_recall` / `persona_` / `scene_summary` / `suggest_` / `daily_review` / `onboarding_guide`	No	Reglas deterministas puramente locales, listas para usar
`memory_extract`	Opcional	Configura `MEMORY_LLM_*` para extracción con LLM (compatible con DeepSeek por defecto); si no se configura, degrada automáticamente al modo de reglas, cero envíos externos
`memory_recall` reescritura de sinónimos	Mejora opcional	Con LLM configurado, añade automáticamente recuperación por sinónimos; sin configurar, usa sinónimos por reglas como respaldo

Ejemplo de configuración opcional (solo memory_extract lo necesita):

# ~/.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

Diferencias de configuración por host

Host	Generación automática de init	Mecanismo de push proactivo	Pasos manuales adicionales
Claude Code	`.mcp.json` + hooks de `.claude/settings.json`	Hooks en tres capas (SessionStart / UserPromptSubmit / Stop)	Ninguno (la TUI interactiva funciona; `claude -p` requiere `--allowedTools`)
Kimi Code	`.mcp.json` + `~/.kimi-code/mcp.json` + `agents/proactive.md` (requiere `init --kimi`)	Impulsado por prompt (`kimi --agent proactive`)	Requiere inicio de sesión/clave de API de Kimi; elegir uno entre esto y kimi-plugin
Cursor	`.mcp.json`	Mapeo oficial de hooks de Claude	Confirmar que .mcp.json es reconocido; activar compatibilidad de hooks de terceros*
Cline	`.mcp.json`	Manual	Conectar `event-capture.js` manualmente (opcional)*
Codex	`.mcp.json`	Manual	Conectar `event-capture.js` manualmente (opcional)*

* El repositorio solo ha sido probado en Claude Code / Kimi Code / Proma; los elementos de Cursor / Cline / Codex se basan en la documentación oficial.

Resumen de capacidades

Tools (20, disponibles en cualquier host)

Categoría	Herramienta	Qué hace
🧠 Escritura de memoria	`memory_capture`	Recordar explícitamente un elemento (preferencia/hecho/corrección/flujo, efecto inmediato; admite scope: project/global)
🧠 Extracción de memoria	`memory_extract`	Pasar la conversación al motor para extracción automática (pendiente de confirmación por defecto, anti-envenenamiento)
🔍 Recuperación de memoria	`memory_recall`	Búsqueda por palabras clave/híbrida, inyecta contexto antes de iniciar la tarea (auto por defecto: proyecto + global combinados)
✅ Cierre de memoria	`memory_pending` / `memory_confirm` / `memory_reject` / `correction_confirm` / `correction_reject`	Confirmación/rechazo de memoria pendiente + correcciones de comportamiento
👤 Perfil	`persona_get` / `persona_save`	Leer perfil combinado (base global + anulaciones de proyecto) / guardar 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: cambios de hoy / días desde la última actualización / invitación a revisión a los 3 días)
💡 Sugerencias	`suggest_now` / `suggest_list` / `suggest_accept` / `suggest_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; futuro: agent/automation/bridge)
📋 Plantillas	`daily_review` / `onboarding_guide`	Revisión diaria / instrucciones de uso

Resources & 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 dinámicas hoy · N días desde la última actualización»; si la memoria no se actualiza en más de 3 días, devuelve una invitación a revisión (limpiar memoria obsoleta, confirmar elementos pendientes, reorganizar el perfil si es necesario); persona_get avisa para simplificar/reorganizar cuando el perfil está sobrecargado (>45 líneas / >6 secciones); 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 abrirlo en el navegador; POST /api/evaluate permite que el host envíe mensajes recientes para activar evaluación en sesión; las tarjetas de sugerencia admiten retroalimentación con un clic «Aceptar / Ignorar» (bucle ActionCard, aceptar materializa la tarea local)
Proceso daemon (0.5.0, salida proactiva): 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 central proactivo; --install configura el autoarranque al iniciar sesión con un clic (launchd / systemd); --status / --stop para gestionar; doctor incluye verificación de salud del daemon y estado de fatiga de hoy (notificadas/límite). Intervalo de inspección PROACTIVE_DAEMON_INTERVAL_MIN (60 minutos por defecto), máximo 1 notificación por vez, sin repetir la misma, sin interrupciones en horario DND y sin descartar sugerencias (principio de moderación).
Control de fatiga de notificaciones (0.8.0): límite diario de notificaciones (6/día por defecto, anulable con PROACTIVE_DAEMON_DAILY_LIMIT, se reinicia automáticamente al cambiar de día) + ventana de enfriamiento (15 minutos por defecto, anulable con PROACTIVE_DAEMON_COOLDOWN_MIN) + 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 y escriben eventos de sesión/mensaje/commit en ~/.proma-proactive/events/ (solo el usuario actual puede leer/escribir), el daemon lee los eventos recientes durante la inspección y construye messages para evaluación programada real (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 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 a un archivo Universal Memory Protocol (.ump/memory.ump.json), ump-import importa desde archivos UMP (pendiente de confirmación por defecto, anti-envenenamiento) — 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 la sesión, envía sugerencias pendientes + escenarios destacados
- UserPromptSubmit (user-prompt): evaluación en tiempo real durante la sesión — si dices «de ahora en adelante usa pnpm», recibes inmediatamente una sugerencia de corrección; las señales débiles se silencian automáticamente
- Stop (session-end): al final de la sesión, consolida 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 scripts, 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 — el modelo de Kimi, al ver 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 la clave de API (kimi la primera vez que ejecutes /login, o configura [providers.<name>] + api_key según config.toml). Si no está configurado, kimi -p reportará 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 transmite proactivamente después de ver <notification>.

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 cometerlo»

你说："以后提交前先写单元测试"
→ 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 daemon 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 en 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 de no molestar	DND (22:30-08:00 por defecto) no genera nuevas sugerencias
Principio de moderación	Máximo 1 sugerencia por vez, presupuesto por sesión, «silencio cuando debe callar»

FAQ

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

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

P: ¿Se necesita una clave de API? R: Las funciones principales (memory_capture / memory_recall / suggest_*, etc.) no la necesitan, funcionan localmente listas para usar; solo la extracción con LLM de memory_extract es opcional. Consulta la «Tabla rápida de requisitos de LLM» en Inicio rápido.

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

P: ¿Se enviarán mis conversaciones a terceros? R: Solo el modo LLM de memory_extract envía el fragmento de conversación actual al LLM que tú mismo configuras (interfaz compatible con DeepSeek por defecto); el modo de reglas tiene cero envíos externos. Capture/recall explícitos son puramente locales.

P: ¿El rendimiento se degradará con mucha memoria? R: Desde 0.5.4, memory_recall usa índice invertido (term → atoms, con caché + invalidación automática + fail-open), solo escanea el conjunto de candidatos que contiene los términos de búsqueda, en lugar de un escaneo completo — sin percepción en proyectos personales/medianos, mantiene baja latencia incluso con decenas de miles de memorias. También se recomienda usar proactive-mcp stats periódicamente para observar el tamaño de la memoria y proactive-mcp archive para 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