universal-memory

Universal Memory (UMem)

Website | Documentação

Uma camada de persistência cognitiva agnóstica de fornecedor para agentes de IA. Elimine o "imposto da repetição" transportando seu contexto, preferências, diretrizes e histórico de forma contínua entre sessões, IDEs e modelos de LLM.

Para ver a ideia central visualmente, confira o design no Excalidraw ou a estrutura da proposta:

Detalhamento do Diagrama

• Memória de Curto Prazo (Efêmera): Memórias específicas do projeto (nível de pasta). Um resumo simples de mudanças recentes, tarefas pendentes e restrições do projeto ou da tarefa.
• Comportamentos dos Agentes: Comporta os comportamentos esperados do agente pelo usuário. Em vez de solicitar as mesmas configurações em todas as sessões, o agente entende o usuário por seus traços, pensamentos e qualquer contexto-chave para melhorar a experiência geral. Isso engloba:
  • Memória de Longo Prazo
  • Memória de Curto Prazo
  • Preferências do Usuário
• Criador de Habilidades: Encapsula a compreensão de fluxos de trabalho específicos. Quando um usuário explica um padrão de tarefa várias vezes, o sistema o traduz em habilidades de agente estruturadas e reutilizáveis.
• Arquivo de Instruções Unificado (AGENTS.md): O ponto de persistência compartilhado consumido por instâncias locais de agentes compatíveis (por exemplo, Agente A, Agente B, Agente C).

O Problema: O "Imposto da Repetição"

Toda vez que você abre uma nova sessão no Claude Code, inicia um novo chat no Cursor, inicia um terminal com OpenCode ou invoca um assistente de IA local, você paga um imposto cognitivo alto:

• Reexplicar sua stack (por exemplo, "Usamos Python 3.12, Typer e Ruff").
• Repetir preferências de estilo de código (por exemplo, "Prefira design funcional, não escreva docstrings a menos que solicitado").
• Copiar e colar esquemas de conexão de banco de dados ou layouts de módulos.
• Explicar metodologias de fluxo de trabalho (por exemplo, "Seguimos Desenvolvimento Orientado por Especificação (SDD)").

A Universal Memory atua como uma camada de persistência local que se conecta automaticamente aos seus runtimes de IA, alinhando-os ao seu fluxo de trabalho, contexto e regras exatos com zero atrito.

Conceitos Arquiteturais Principais

1. Modelo de Memória Dupla

• Memória de Curto Prazo (Escopo do Projeto): Contexto efêmero e específico do diretório. Rastreia o que você fez há 10 minutos, tarefas ativas atuais e restrições imediatas.
• Memória Universal (Escopo Global): Preferências de longa duração, diretrizes de estilo, configurações de ferramentas e identidade.

2. Mecanismo de Auto-Adaptação

Em vez de copiar e colar instruções, o umem monitora o contexto da sua sessão e atualiza automaticamente os manifestos de instruções do projeto ativo (AGENTS.md, CLAUDE.md, .cursor/rules/, etc.), impondo consistência operacional em todos os agentes.

3. Integração com o Model Context Protocol (MCP)

Integre o umem nativamente com qualquer cliente que suporte o MCP padrão (como Claude Desktop ou Cursor). Os agentes de IA podem recuperar contexto programaticamente, aprender novos fatos e sugerir habilidades em tempo real.

4. Padrão de Habilidades de Agente

Encapsula instruções processuais complexas e repetitivas em Habilidades de Agente formais (em conformidade com o padrão agentskills.io), completas com diretórios estruturados contendo instruções SKILL.md, scripts/ auxiliares e documentação references/.

A Universal Memory mantém uma única fonte canônica para cada habilidade. Habilidades de projeto compartilhadas e voltadas ao usuário ficam em umem/skills/<slug>/SKILL.md; habilidades de projeto privadas, operacionais e legadas ficam em .umem/skills/<slug>/SKILL.md. Pastas nativas de runtime como .agents/skills/, .opencode/skills/ e .antigravity/rules/ recebem cópias sincronizadas completas para que cada agente possa consumir a mesma habilidade em seu layout esperado.

Instalação e Configuração

Certifique-se de ter o Python 3.12+ instalado. Você pode executar ou instalar o umem usando seu gerenciador de pacotes preferido.

Experimente instantaneamente com uvx

Você pode executar o umem sem instalá-lo permanentemente:

uvx --from universal-memory umem --help

[!WARNING] O uvx é melhor para testes rápidos. Para uso contínuo, instale a Universal Memory como uma ferramenta persistente para que o umem esteja sempre disponível e possa gerenciar totalmente memórias globais de longa duração e habilidades de agente sincronizadas:

uv tool install universal-memory

Instalar via PyPI

pip install universal-memory

Atualizar a Universal Memory

O umem update não atualiza o pacote Python do PyPI. Ele realiza manutenção local e offline para o workspace atual do .umem, como migrações de esquema, atualizações de benchmark e sincronização de habilidades.

Para atualizar o executável instalado do umem, use o gerenciador de pacotes que o instalou:

# 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

Confirme o executável que você está executando:

umem --version
which umem

Atualizar o executável não muta silenciosamente projetos existentes. Na próxima vez que você trabalhar em um projeto inicializado, reconcilie-o localmente:

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

Você não precisa executar o umem init novamente. A manutenção local cria snapshots e registros de auditoria antes das gravações de propriedade do UMEM. Árvores .umem/skills/use-universal-memory/ existentes e arquivos gerenciados personalizados são preservados; se raízes de habilidades legadas e canônicas da Universal Memory existirem, o UMEM para para uma decisão explícita de migração em vez de mesclar ou excluir qualquer uma das árvores.

Guia de Início Rápido

1. Inicialize seu projeto

Abra o diretório do seu projeto e execute:

umem init

A Universal Memory detecta os agentes já usados no workspace, apresenta uma confirmação combinada, configura a melhor integração de projeto disponível e verifica se o agente pode ler o contexto do projeto. Você não precisa escolher um mecanismo de integração nem saber quais arquivos de instrução ele usa.

Quando um agente compatível precisar da Habilidade de Agente portátil, o UMEM divulga qualquer uso de rede e cópia externa no escopo do projeto antes da confirmação, desativa telemetria anônima do instalador e trata um pré-requisito ausente ou uma instalação com falha como recuperável em vez de bloquear a inicialização.

Para conectar outro agente mais tarde, execute:

umem connect

A seleção explícita de runtime permanece disponível para automação e configurações incomuns, mas não é necessária para o caminho 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. Inicialize uma sessão de agente

No início de cada conversa ou sessão de agente, prefira a ferramenta MCP bootstrap() quando estiver conectada. Caso contrário, use o comando CLI equivalente:

umem bootstrap --format json

Esta única chamada valida a integração e retorna o status do projeto, o contexto ativo do projeto e o catálogo de habilidades. Trate data.context como contexto ativo, inspecione data.skills.list e solicite detalhes apenas para habilidades relevantes à tarefa atual:

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

Execute o bootstrap apenas uma vez por conversa ou sessão. Ele substitui a sequência de inicialização anterior de chamadas separadas status, context e skills list; ele não realiza instalação, sincronização ou configuração.

3. Salve suas primeiras preferências e fatos

Diga ao umem o que manter em mente. Você pode direcionar o escopo do projeto (esta pasta) ou o escopo global (em todos os projetos):

# 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. Recupere o Contexto

Verifique o resumo de contexto consolidado gerado pela combinação de fatos de curto prazo, regras e preferências globais:

umem context --scope project

5. Adote ou crie uma Habilidade de Agente

Se uma habilidade já existir, escolha primeiro o caminho de adoção mais seguro. Use adopt para um diretório .umem/skills/<slug> existente; use import para diretórios nativos de runtime como .agents/skills/<slug> e sincronize-o de volta para os runtimes 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

Se você estiver começando do zero, rascunhe e publique sem efeitos colaterais 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 um fluxo de trabalho em uma etapa, crie a habilidade canônica. Ela é somente canônica por padrão; solicite a sincronização explicitamente quando os alvos nativos de runtime devem ser gravados:

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

Após editar .umem/skills/review-protocol/SKILL.md, atualize uma habilidade de runtime com:

umem skills sync review-protocol

6. Verifique status e saúde

umem status

Integração de Host e Matriz de Suporte

O UMEM separa deliberadamente a propriedade nativa da compatibilidade portátil:

As superfícies de integração mantidas e nomeadas são:

Um agente que aparece no catálogo externo skills não o torna Nível 1. O Nível 1 é intencionalmente pequeno e requer um adaptador mantido, evidência de lançamento e validação repetível específica do host. Consulte o guia de Introdução para o comportamento de projetos legados e o fluxo de instalação portátil.

Executando como um Servidor Model Context Protocol (MCP)

Os agentes de IA podem interagir diretamente com sua memória por meio do Model Context Protocol. A configuração manual do MCP para um host sem um fluxo de trabalho UMEM programado é Nível 3: a disponibilidade da ferramenta é validada, mas o carregamento de instruções e o comportamento do agente não são garantidos.

Comando de Lançamento Único

uvx --from universal-memory umem-mcp

Comando de Lançamento com Instalação Persistente

umem-mcp

Bootstrap Uma Vez por Sessão

Quando o servidor MCP estiver conectado, os agentes devem chamar bootstrap() uma vez no início da conversa ou sessão. É semanticamente equivalente a umem bootstrap --format json: ambos retornam status, contexto ativo do projeto e o catálogo de habilidades, e ambos preservam o mesmo comportamento de erro rápido. Os detalhes das habilidades permanecem separados e devem ser solicitados apenas para habilidades relevantes selecionadas.

Exemplo de Configuração: Claude Desktop (claude_desktop_config.json)

Use o formulário uvx quando a Universal Memory não estiver instalada como uma ferramenta persistente:

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

Se você instalou a Universal Memory com uv tool install universal-memory ou pipx install universal-memory, use o entrypoint estável:

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

Solucione problemas de inicialização com:

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

Para hosts MCP iniciados por GUI, use o caminho absoluto para uvx se o host não herdar as variáveis de ambiente do seu shell PATH.

Segurança e Salvaguardas

• Scanner de Segredos de API: umem passa todas as informações recebidas por um scanner passivo para bloquear chaves de API, tokens ou credenciais de serem armazenados em sua base cognitiva persistente.
• Snapshots e Rollbacks: Toda atualização automatizada dos seus arquivos de configuração (AGENTS.md, CLAUDE.md) é precedida por um backup de snapshot. Você pode reverter a qualquer momento:

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

• Proteção contra Deriva de Habilidades: umem skills sync detecta deriva nativa gerenciada e mantém alterações locais por padrão. Use --drift-decision overwrite somente quando você intencionalmente quiser que o conteúdo canônico do UMEM substitua a cópia nativa gerenciada.
• Limite da Ponte Externa: A instalação de Nível 2 através de npx skills é uma mutação externa explicitamente confirmada. O UMEM desativa a telemetria anônima do instalador, restringe o alvo ao projeto atual e valida o resultado completo, mas rotula a escrita como executada externamente em vez de reivindicar propriedade de snapshot do UMEM.

Gerenciando Habilidades de Agentes

Você pode redigir, criar, adotar, importar, validar, manter e sincronizar comportamentos 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

Licença

Distribuído sob a Licença Apache 2.0. Consulte LICENSE e NOTICE para mais informações.