universal-memory

Universal Memory (UMem)

Sitio web | Documentación

Una capa de persistencia cognitiva independiente del proveedor para agentes de IA. Elimina el "impuesto de repetición" transportando tu contexto, preferencias, directrices e historial sin problemas entre sesiones, IDEs y modelos de LLM.

Para ver la idea central visualmente, consulta el diseño de Excalidraw o la estructura de la propuesta:

Desglose del diagrama

• Memoria a corto plazo (efímera): Memorias específicas del proyecto (a nivel de carpeta). Un resumen simple de cambios recientes, tareas pendientes y restricciones a nivel de proyecto o tarea.
• Comportamientos de agentes: Incluye los comportamientos esperados del agente por parte del usuario. En lugar de solicitar la misma configuración en cada sesión, el agente entiende al usuario por sus rasgos, pensamientos y cualquier contexto clave para mejorar la experiencia general. Esto abarca:
  • Memoria a largo plazo
  • Memoria a corto plazo
  • Preferencias del usuario
• Creador de habilidades: Encapsula la comprensión de flujos de trabajo específicos. Cuando un usuario explica un patrón de tarea varias veces, el sistema lo traduce en habilidades de agente estructuradas y reutilizables.
• Archivo de instrucciones unificado (AGENTS.md): El punto final de persistencia compartido consumido por instancias de agentes locales compatibles (por ejemplo, Agente A, Agente B, Agente C).

El problema: el "impuesto de repetición"

Cada vez que abres una nueva sesión en Claude Code, inicias un nuevo chat en Cursor, levantas una terminal con OpenCode o invocas un asistente de IA local, pagas un elevado impuesto cognitivo:

• Reexplicar tu stack (por ejemplo, "Usamos Python 3.12, Typer y Ruff").
• Repetir preferencias de estilo de código (por ejemplo, "Prefiere diseño funcional, no escribas docstrings salvo que se solicite").
• Copiar y pegar esquemas de conexión a bases de datos o diseños de módulos.
• Explicar metodologías de trabajo (por ejemplo, "Seguimos desarrollo dirigido por especificaciones (SDD)").

Universal Memory actúa como una capa de persistencia local que se conecta automáticamente a tus entornos de ejecución de IA, alineándolos con tu flujo de trabajo, contexto y reglas exactos sin fricción.

Conceptos arquitectónicos clave

1. Modelo de memoria dual

• Memoria a corto plazo (alcance del proyecto): Contexto efímero y específico del directorio. Realiza un seguimiento de lo que hiciste hace 10 minutos, las tareas activas actuales y las restricciones inmediatas.
• Memoria universal (alcance global): Preferencias de larga duración, directrices de estilo, configuraciones de herramientas e identidad.

2. Motor de auto-adaptación

En lugar de copiar y pegar instrucciones, umem supervisa el contexto de tu sesión y actualiza automáticamente los manifiestos de instrucciones del proyecto activo (AGENTS.md, CLAUDE.md, .cursor/rules/, etc.), aplicando consistencia operativa en todos los agentes.

3. Integración con el Protocolo de Contexto de Modelo (MCP)

Integra umem de forma nativa con cualquier cliente que admita el MCP estándar (como Claude Desktop o Cursor). Los agentes de IA pueden recuperar contexto programáticamente, aprender nuevos datos y sugerir habilidades sobre la marcha.

4. Estándar de habilidades de agente

Encapsula instrucciones procedimentales complejas y repetitivas en habilidades de agente formales (conforme al estándar agentskills.io), completas con directorios estructurados que contienen instrucciones SKILL.md, scripts/ auxiliares y documentación references/.

Universal Memory mantiene una única fuente canónica para cada habilidad. Las habilidades de proyecto compartidas y orientadas al usuario viven en umem/skills/<slug>/SKILL.md; las habilidades de proyecto privadas, operativas y heredadas viven en .umem/skills/<slug>/SKILL.md. Las carpetas nativas de entornos de ejecución como .agents/skills/, .opencode/skills/ y .antigravity/rules/ reciben copias sincronizadas completas para que cada agente pueda consumir la misma habilidad en su diseño esperado.

Instalación y configuración

Asegúrate de tener Python 3.12+ instalado. Puedes ejecutar o instalar umem usando tu gestor de paquetes preferido.

Prueba al instante con uvx

Puedes ejecutar umem sin instalarlo permanentemente:

uvx --from universal-memory umem --help

[!ADVERTENCIA] uvx es mejor para pruebas rápidas. Para uso continuo, instala Universal Memory como una herramienta persistente para que umem esté siempre disponible y pueda gestionar completamente memorias globales de larga duración y habilidades de agente sincronizadas:

uv tool install universal-memory

Instalar vía PyPI

pip install universal-memory

Actualizar Universal Memory

umem update no actualiza el paquete de Python desde PyPI. Realiza mantenimiento local y sin conexión para el espacio de trabajo actual de .umem, como migraciones de esquema, actualizaciones de referencia y sincronización de habilidades.

Para actualizar el ejecutable instalado de umem, usa el gestor de paquetes que lo instaló:

# If installed with uv tool
uv tool upgrade universal-memory

# If installed with pipx
pipx upgrade universal-memory

# If installed with pip
python -m pip install --upgrade universal-memory

# If running temporarily with uvx
uvx --refresh --from universal-memory umem --version

Confirma el ejecutable que estás usando:

umem --version
which umem

Actualizar el ejecutable no muta silenciosamente los proyectos existentes. La próxima vez que trabajes en un proyecto inicializado, concílialo localmente:

umem update --check
umem update
umem update --skills
umem connect
umem doctor

No necesitas ejecutar umem init de nuevo. El mantenimiento local crea instantáneas y registros de auditoría antes de las escrituras propiedad de UMEM. Los árboles .umem/skills/use-universal-memory/ existentes y los archivos gestionados personalizados se conservan; si existen tanto las raíces de habilidades de Universal Memory heredadas como las canónicas, UMEM se detiene para una decisión de migración explícita en lugar de fusionar o eliminar cualquiera de los árboles.

Guía de inicio rápido

1. Inicializa tu proyecto

Abre el directorio de tu proyecto y ejecuta:

umem init

Universal Memory detecta los agentes ya utilizados en el espacio de trabajo, presenta una confirmación combinada, configura la mejor integración de proyecto disponible y verifica que el agente pueda leer el contexto del proyecto. No necesitas elegir un mecanismo de integración ni saber qué archivos de instrucciones usa.

Cuando un agente compatible necesita la Habilidad de Agente portátil, UMEM revela cualquier uso de red y copia externa con alcance de proyecto antes de la confirmación, desactiva la telemetría anónima del instalador y trata un requisito previo faltante o una instalación fallida como recuperable en lugar de bloquear la inicialización.

Para conectar otro agente más tarde, ejecuta:

umem connect

La selección explícita de entorno de ejecución sigue disponible para automatización y configuraciones inusuales, pero no es necesaria para la ruta normal.

DISABLE_TELEMETRY=1 npx --yes skills@1.5.20 add https://github.com/YanAmorelli/universal-memory/tree/v0.6.1/skills/universal-memory --skill universal-memory --agent pi --copy -y

2. Inicializa una sesión de agente

Al inicio de cada conversación o sesión de agente, prefiere la herramienta MCP bootstrap() cuando esté conectada. De lo contrario, usa el comando CLI equivalente:

umem bootstrap --format json

Esta única llamada valida la integración y devuelve el estado del proyecto, el contexto activo del proyecto y el catálogo de habilidades. Trata data.context como contexto activo, inspecciona data.skills.list y solicita detalles solo para las habilidades relevantes a la tarea actual:

umem skills detail <skill-id-or-name> --format json

Ejecuta la inicialización solo una vez por conversación o sesión. Reemplaza la secuencia de inicio anterior de llamadas separadas a status, context y skills list; no realiza instalación, sincronización ni configuración.

3. Guarda tus primeras preferencias y datos

Dile a umem qué debe tener en cuenta. Puedes apuntar al alcance del proyecto (esta carpeta) o al alcance global (en todos los proyectos):

# Save a global preference
umem remember --scope global "Yan is a solutions architect specializing in AI applications"

# Save a project-specific constraint
umem remember --scope project "Always use Tomllib instead of PyYAML for configuration files" --tag config

4. Recupera el contexto

Verifica el resumen de contexto consolidado generado combinando datos a corto plazo, reglas y preferencias globales:

umem context --scope project

5. Adopta o crea una Habilidad de Agente

Si ya existe una habilidad, elige primero la ruta de adopción más segura. Usa adopt para un directorio .umem/skills/<slug> existente; usa import para directorios nativos de entornos de ejecución como .agents/skills/<slug> y sincronízalo de vuelta a los entornos configurados:

umem skills adopt .umem/skills/review-protocol --scope project
umem skills import .agents/skills/review-protocol --scope project --sync
umem skills detail review-protocol

Si empiezas desde cero, redacta y publica sin efectos secundarios nativos:

umem skills draft create \
  --name "Review Protocol" \
  --description "Reusable review workflow" \
  --trigger "when reviewing code"
umem skills draft validate review-protocol
umem skills publish review-protocol --format summary

Para un flujo de trabajo de un solo paso, crea la habilidad canónica. Es solo canónica por defecto; solicita la sincronización explícitamente cuando se deban escribir los destinos nativos del entorno de ejecución:

umem skills create \
  --name "Review Protocol" \
  --description "Reusable review workflow" \
  --trigger "when reviewing code" \
  --format summary
umem skills sync review-protocol --check-gitignore --format summary

Después de editar .umem/skills/review-protocol/SKILL.md, actualiza una habilidad del entorno de ejecución con:

umem skills sync review-protocol

6. Verifica el estado y la salud

umem status

Integración de host y matriz de soporte

UMEM separa deliberadamente la propiedad nativa de la compatibilidad portátil:

Las superficies de integración mantenidas y nombradas son:

Un agente que aparece en el catálogo externo skills no lo convierte en Nivel 1. El Nivel 1 es intencionalmente pequeño y requiere un adaptador mantenido, evidencia de lanzamiento y validación específica del host repetible. Consulta la guía de inicio para el comportamiento de proyectos heredados y el flujo de instalación portátil.

Ejecución como servidor del Protocolo de Contexto de Modelo (MCP)

Los agentes de IA pueden interactuar directamente con tu memoria a través del Protocolo de Contexto de Modelo. La configuración manual de MCP para un host sin un flujo de trabajo UMEM programado es Nivel 3: se valida la disponibilidad de la herramienta, pero la carga de instrucciones y el comportamiento del agente no están garantizados.

Comando de lanzamiento único

uvx --from universal-memory umem-mcp

Comando de lanzamiento de instalación persistente

umem-mcp

Inicialización única por sesión

Cuando el servidor MCP está conectado, los agentes deben llamar a bootstrap() una vez al inicio de la conversación o sesión. Es semánticamente equivalente a umem bootstrap --format json: ambos devuelven estado, contexto de proyecto activo y el catálogo de habilidades, y ambos preservan el mismo comportamiento de error de fallo rápido. Los detalles de habilidades permanecen separados y deben solicitarse solo para las habilidades relevantes seleccionadas.

Ejemplo de configuración: Claude Desktop (claude_desktop_config.json)

Usa la forma uvx cuando Universal Memory no esté instalado como herramienta persistente:

{
  "mcpServers": {
    "universal-memory": {
      "command": "uvx",
      "args": [
        "--from",
        "universal-memory",
        "umem-mcp"
      ]
    }
  }
}

Si instalaste Universal Memory con uv tool install universal-memory o pipx install universal-memory, usa el punto de entrada estable:

{
  "mcpServers": {
    "universal-memory": {
      "command": "umem-mcp",
      "args": []
    }
  }
}

Soluciona problemas de inicio con:

uvx --from universal-memory umem doctor
uvx --from universal-memory umem-mcp --help

Para hosts de MCP lanzados mediante GUI, usa la ruta absoluta a uvx si el host no hereda el PATH de tu shell.

Seguridad y Salvaguardas

• Escáner de Secretos de API: umem pasa todos los hechos entrantes por un escáner pasivo para bloquear claves de API, tokens o credenciales de ser almacenados en tu base cognitiva persistente.
• Instantáneas y Reversiones: Cada actualización automática de tus archivos de configuración (AGENTS.md, CLAUDE.md) está precedida por una copia de seguridad instantánea. Puedes revertir en cualquier momento:

  # View audit logs
  umem audit list --scope project
  
  # Revert last automated modification
  umem rollback --scope project
  

• Protección contra Deriva de Habilidades: umem skills sync detecta la deriva nativa gestionada y conserva los cambios locales por defecto. Usa --drift-decision overwrite solo cuando quieras intencionalmente que el contenido canónico de UMEM reemplace la copia nativa gestionada.
• Límite del Puente Externo: La instalación de Nivel 2 a través de npx skills es una mutación externa explícitamente confirmada. UMEM desactiva la telemetría anónima del instalador, restringe el objetivo al proyecto actual y valida el resultado completo, pero etiqueta la escritura como ejecutada externamente en lugar de reclamar propiedad de instantánea de UMEM.

Gestión de Habilidades de Agente

Puedes redactar, crear, adoptar, importar, validar, mantener y sincronizar comportamientos especializados:

# List all active skills
umem skills list

# Inspect one skill
umem skills detail review-protocol

# Draft, validate, and publish without native runtime writes
umem skills draft create --name "Review Protocol" --description "Reusable review workflow"
umem skills draft validate review-protocol
umem skills publish review-protocol

# Create a new canonical skill and explicitly sync native targets
umem skills create --name "Review Protocol" --description "Reusable review workflow" --sync

# Adopt existing canonical work
umem skills adopt .umem/skills/review-protocol --scope project

# Import an existing native skill and distribute complete runtime copies
umem skills import .agents/skills/review-protocol --scope project --sync

# Validate and maintain canonical skills
umem skills validate review-protocol
umem skills canonical update review-protocol --file .umem/skills/review-protocol/SKILL.md
umem skills rename review-protocol --slug review-checklist
umem skills cleanup review-checklist --targets --format summary
umem skills cleanup review-checklist --targets --apply
umem skills repair --remove-orphan-targets --format summary

# Synchronize one canonical skill into active native runtime folders
umem skills sync review-protocol --check-gitignore --format summary

# Synchronize all active canonical skills during maintenance
umem update --skills

# Track and review recurring workflow candidates
umem skills track --name "Review Protocol" --description "Recurring review workflow"
umem skills recommend --scope project
umem skills propose <latent-skill-id> --decision yes
umem skills promote <recommendation-id> --yes
umem skills generate <latent-skill-id> --yes

Licencia

Distribuido bajo la Licencia Apache 2.0. Consulta LICENSE y NOTICE para más información.