🧠 Maess Memory CLI

Maess Memory é uma camada de memória externa para agentes de IA.

Ele captura, organiza e reutiliza conhecimento automaticamente — sem você precisar repetir contexto a cada interação.

Repositório do projeto: https://github.com/maess-memory/maess-memory-cli

⚡ Teste em 1 minuto

1. Instale

npm i @maess-systems/memory-cli

Pré-requisitos para usar o CLI:

• Docker instalado
• Codex CLI instalado

2. Configure

npx maess init

3. Suba o ambiente

npx maess start

4. Teste a memória

👉 Prompt 1 — registrar memória:

Estou iniciando um projeto chamado "Sistema de Gestão de Sinistros".

Decisão importante:

• Backend será .NET com arquitetura DDD + Hexagonal
• Banco de dados MongoDB
• Multi-tenant obrigatório

Registre isso como uma memória técnica de longo prazo.

👉 Prompt 2 — recuperar memória:

Quais decisões técnicas já foram registradas para o sistema de gestão de sinistros?

👉 Prompt 3 — usar memória automaticamente:

Sugira arquitetura para meu projeto

💡 O sistema vai lembrar automaticamente do contexto e responder com base nisso.

5. Veja a memória persistida

Abra:

http://localhost:3000

6. Acesso ao sistema

As credenciais de acesso são geradas automaticamente no arquivo .env durante o init.

Use:

• Usuário: BOOTSTRAP_ADMIN_USUARIO_EMAIL
• Senha: BOOTSTRAP_ADMIN_USUARIO_SECRET

💡 Esses valores ficam disponíveis no arquivo .env na raiz do projeto.

🧠 O que está acontecendo

• Memórias são capturadas automaticamente via hooks
• O sistema recupera contexto relevante em cada prompt
• O modelo responde considerando histórico real
• Tudo fica persistido e auditável

🚀 Comandos principais

npx maess init
npx maess start
npx maess status
npx maess logs
npx maess clear-config
npx maess uninstall

🔧 Comandos avançados

npx maess clear-config
npx maess uninstall
npx maess stop
npx maess restart
npx maess down

⚙️ O que o init faz

• cria ou atualiza .env
• instala hooks do Codex (.codex/)
• prepara integração com MCP
• deixa o projeto pronto para usar memória

Se Docker ou Codex não estiverem instalados, o comando npx maess init interrompe a execução e mostra o que precisa ser ajustado antes do setup.

Se o arquivo ~/.codex/config.toml ainda não existir, o init cria esse arquivo automaticamente antes de aplicar a configuração.

Ao executar npx maess start, o CLI também valida se a porta HTTP configurada em HOST_HTTP_PORT está livre antes de subir a stack.

🧹 Como limpar a configuração do Codex

Se quiser remover do ~/.codex/config.toml tudo o que o Maess Memory adicionou, rode:

npx maess clear-config

Esse comando remove:

• a ativação de hooks adicionada pelo CLI
• o bloco mcp_servers.maess-memory

Ele não remove os arquivos locais do projeto, como .codex/, .env ou .maess/.

🗑️ Como desinstalar do projeto

Se quiser desfazer o setup completo do projeto, rode:

npx maess uninstall

Esse é o comando recomendado quando você terminou um estudo, prova de conceito ou teste local e quer deixar o ambiente limpo, sem referências do Maess Memory no projeto e no Codex.

Esse comando:

• executa docker compose down -v da stack do Maess Memory, quando .maess/ existe
• remove do ~/.codex/config.toml os blocos gerenciados pelo Maess Memory
• remove .codex/hooks, .codex/hooks.json e tenta limpar .codex/ se ele ficar vazio
• remove o diretório .maess/
• remove do .env apenas as chaves adicionadas pelo init

Depois do uninstall, o projeto volta a ficar sem hooks, sem MCP server configurado pelo Maess Memory e sem os arquivos locais gerados pelo setup.

🔌 Portas usadas

• o host da aplicação usa HOST_HTTP_PORT, que por padrão é 3000
• o MongoDB não é exposto para a máquina local; ele fica disponível apenas na rede interna do Docker Compose

Se a porta 3000 já estiver em uso, altere HOST_HTTP_PORT no .env antes de rodar npx maess start.

💡 Por que usar

Sem Maess Memory:

• você repete contexto
• perde decisões
• respostas são genéricas

Com Maess Memory:

• o agente lembra
• decisões são reutilizadas
• respostas evoluem com o projeto

🧠 Conceito

Maess Memory não é só armazenamento.

É uma infra de memória contextual para agentes:

• multi-tenant
• orientado a contexto
• auditável
• pronto para escalar

💡 Dica

Você também pode usar:

npx maess-memory

Mas o recomendado é:

npx maess

🚀 Próximos passos

• suporte a múltiplos usuários
• planos com funcionalidades avançadas
• versão cloud (sem necessidade de infra local)