OmniMem
oficialUm servidor MCP auto-hospedado que dá aos Agentes de IA memória persistente entre sessões, projetos e máquinas.
O que você pode fazer com OmniMem MCP?
Dê ao seu agente de IA uma memória persistente e auto-hospedada entre sessões, projetos e máquinas — peça para ele "verificar o cemitério antes de sugerir uma biblioteca que já falhou."
- Briefing de sessão — Peça um
briefingpara obter contexto do projeto, estatísticas de experiência, memórias obsoletas, novos artigos e sugestões de habilidades em uma única chamada. - Evite becos sem saída do passado — Faça o agente verificar o cemitério antes de sugerir uma biblioteca ou padrão que falhou anteriormente.
- Lembre decisões passadas — Use
recallpara trazer à tona decisões, correções e padrões de sessões anteriores entre projetos. - Registre experiência conquistada com esforço — Registre uma correção com
record_experiencepara que lições que exigiram esforço real apareçam mais facilmente na próxima vez. - Remova duplicatas de memórias — Execute
find_duplicatespara sinalizar e limpar em massa memórias armazenadas quase idênticas. - Faça backup da sua memória — Exporte tudo para um arquivo JSON que você controla com
dump_to_file.
Documentação
Self-hosted semantic memory for AI Agents. Persistent sessions, experience scoring, and a graveyard for dead ends, backed by knowledge acquired from the RSS you read and stored in a Valkey vector search then exposed as an MCP server. https://omnimem.org
<OmniMem>omnimem.org
O desenvolvimento acontece no Codeberg — issues e PRs por favor.
Pare de viver a mesma sessão duas vezes.
Toda sessão do Claude Code começa do zero. Sem memória do seu projeto. Sem memória do que falhou na semana passada. Sem memória de que você passou três horas na terça-feira passada descobrindo por que o onnxruntime explode no Alpine antes de encontrar algo que realmente funciona.
Então você explica o projeto de novo. O Claude sugere a mesma biblioteca quebrada de novo. Mesmo alarme. Mesma música. Você é o Bill Murray e o Claude é Punxsutawney.
O OmniMem resolve isso. É um servidor MCP auto-hospedado que dá ao seu agente de IA memória persistente entre sessões, projetos e máquinas. Ele roda no seu próprio hardware e é gratuito para sempre.
claude> use onnxruntime for the embeddings
⚠ WARNING: previously abandoned approach
onnxruntime — SIGILL crash on Alpine musl libc (effort: 4/5)
→ switched to sentence-transformers instead
Esse aviso veio da memória, não da sorte. O erro pelo qual você já pagou não pode cobrar de novo.
Comece rapidamente
Dica
Um comando coloca toda a stack em funcionamento a partir das imagens pré-construídas do Docker Hub:
curl -fsSL https://codeberg.org/ric_harvey/omnimem/raw/branch/main/install.sh | bashDepois aponte seu agente para ele — o quick start explica o restante, ou pule para a seção de início rápido mais completa abaixo.
O que ele lembra
Cinco tipos de memória, todos pesquisados juntos no momento da recuperação:
- Episódica — as decisões que você tomou, os bugs que corrigiu, os padrões que descobriu. As coisas que exigiram esforço real para aprender e não deveriam ser reaprendidas toda manhã.
- Contexto do projeto — sua stack, objetivos e estado atual. O agente chega a cada sessão já informado, em vez de começar do zero.
- Conhecimento — feeds RSS que você configura, buscados em um cronograma, resumidos pelo Claude Haiku, incorporados e armazenados. Quando um artigo relevante chegou na semana passada, ele aparece como um ponto de partida que vale a pena ler.
- Preferências — regras prescritivas sobre como você quer trabalhar ("sempre atualize o README depois que uma funcionalidade for lançada"), extraídas automaticamente das suas conversas e exibidas sempre que se aplicam.
- Habilidades — documentos SKILL.md compilados a partir da sua experiência acumulada em um domínio, para que o agente trabalhe do seu jeito desde o primeiro prompt. Derivados dos outros namespaces, nunca editados manualmente, e toda mudança passa pela sua revisão. Veja o compilador de habilidades. O principal resultado de recall pode ser uma decisão de seis meses atrás em um projeto diferente, uma solução de ontem ou um artigo que chegou na terça à noite. Não importa de onde veio, desde que seja útil.
O que o torna diferente
Não é apenas um armazenamento chave-valor com um wrapper MCP. O OmniMem modela como a memória realmente funciona: as coisas desaparecem com o tempo, às vezes se contradizem, e o que foi conquistado com esforço ganha seu lugar.
- O Cemitério — todo beco sem saída é registrado com o que você tentou, por que falhou e quanto tempo você gastou. O agente verifica antes de sugerir uma biblioteca ou padrão.
- Pontuação de experiência — algo que exigiu quatro tentativas e uma solução alternativa estranha de plataforma para ser resolvido é ouro. Quanto mais difícil foi, mais facilmente ele aparece na próxima vez.
- Ciclo de vida da memória —
ACTIVE → DEPRIORITISED → ARCHIVED → DELETED. "Esqueça X" geralmente significa parar de mencioná-lo, não apagá-lo da existência. Memórias despriorizadas podem reconquistar seu lugar. - Detecção de contradição — se uma nova memória discorda de algo armazenado, o OmniMem detecta. Heurística rápida em cada gravação, análise mais profunda opcional via Claude Haiku.
- Deduplicação semântica — memórias quase idênticas são sinalizadas no momento da gravação e limpas em massa com
find_duplicates(). - Briefing em uma chamada — um único
briefing()retorna contexto do projeto, estatísticas de experiência, memórias desatualizadas, novos artigos, avisos de contradição e sugestões de habilidades. Sem aquecimento em três etapas. - O compilador de habilidades — destila lições reforçadas e becos sem saída em habilidades carregáveis, atrás de um portão de propor-e-aceitar para que lições ruins não se tornem política silenciosamente.
- Manutenção automática — duplicatas arquivadas, contradições sinalizadas, conhecimento expirado limpo, tudo em segundo plano.
- Interface Web — navegue, pesquise e gerencie tudo a partir de um painel htmx, com telemetria e um endpoint
/metricsdo Prometheus.
A fórmula de classificação por trás de cada recall:
score = similarity x surface_score x recency x experience_weight
Quatro fatores decidem o que volta. A similaridade semântica sozinha não é suficiente — o estado do ciclo de vida, a idade e o quão difícil foi aprender a lição desempenham um papel.
Funciona com qualquer agente MCP
Uma camada de memória para todos eles: claude.ai, Claude Code, Claude Desktop, Cursor, GitHub Copilot, GitLab Duo, AWS Kiro, OpenCode, OpenAI Codex CLI e Open Design.
Arquitetura
Quatro contêineres. Nada sai da sua máquina. Embeddings locais via sentence-transformers, armazenamento em Valkey com busca vetorial, e ambas as portas de entrada compartilham o mesmo mecanismo de memória.
flowchart TB
agent["AI agent<br/>Claude Code · claude.ai · Cursor · Copilot · ..."]
browser["Browser"]
agent -- "MCP · Streamable HTTP / SSE · :8765" --> mcp
browser -- "HTTP · :8080" --> webui
subgraph stack["Docker Compose stack"]
mcp["MCP server<br/>Python · FastMCP<br/><i>remember · recall · briefing<br/>compile_skill · record_experience</i>"]
webui["Web UI<br/>Starlette · htmx · Jinja2<br/><i>dashboard · search · skills<br/>projects · backups · /metrics</i>"]
rss["RSS worker<br/>feedparser · APScheduler<br/>Claude Haiku summaries"]
valkey[("Valkey + valkey-search<br/>HNSW vector indexes<br/><i>idx:episodic · idx:project · idx:knowledge<br/>idx:preference · idx:skill</i>")]
mcp <--> valkey
webui <--> valkey
rss --> valkey
end
O quadro completo — o pipeline de recall, o modelo de armazenamento e as decisões de design — está em docs/architecture.md.
Auto-hospedado, código aberto, seu
Sem SaaS. Sem dependência de fornecedor. Nenhum contexto enviado para servidores de terceiros.
- Valkey é um fork de código aberto do Redis. Todos os seus dados permanecem em um volume Docker nomeado na sua própria máquina.
- Imagens Docker multi-arquitetura para amd64 e arm64. Funciona em Raspberry Pi, AWS Graviton ou Apple Silicon tão bem quanto em x86.
- sentence-transformers executa embeddings localmente sem chamadas de API.
- Licença MIT significa que você pode fazer fork, estender e executar onde quiser.
- Um comando de backup chama
dump_to_file()e exporta tudo para um arquivo JSON que você possui.
Exponha a porta MCP através do seu proxy reverso e todas as máquinas a partir das quais você trabalha compartilham a mesma memória. Uma implantação, em qualquer lugar — veja docs/remote-access.md.
Início rápido
O instalador verifica se o Docker está instalado, gera senhas seguras, escreve um .env sensato e inicia tudo a partir das imagens pré-construídas do Docker Hub:
curl -fsSL https://codeberg.org/ric_harvey/omnimem/raw/branch/main/install.sh | bash
Ou compile a partir do código-fonte:
git clone https://codeberg.org/ric_harvey/omnimem.git && cd omnimem
cp .env.example .env
# Set VALKEY_PASSWORD and ANTHROPIC_API_KEY in .env
docker compose up -d
Em seguida, aponte seu agente para ele — Claude Code (~/.claude.json):
{
"mcpServers": {
"omnimem": {
"type": "sse",
"url": "http://localhost:8765/sse"
}
}
}
O servidor entrega seu guia de uso a qualquer agente conectado automaticamente via campo instructions do MCP — nenhum arquivo de configuração necessário. O painel web está em http://localhost:8080.
O passo a passo completo, incluindo tokens de autenticação, configurações de permissão e os outros agentes, está em docs/quick-start.md.
Documentação
| Início rápido | Instalador, compilação a partir do código-fonte, conexão do seu agente |
| Recursos em profundidade | Ciclo de vida, cemitério, pontuação de experiência, deduplicação, contradições, briefing |
| O compilador de habilidades | Compilando experiência em habilidades carregáveis |
| Referência de ferramentas MCP | Todas as 30+ ferramentas |
| Referência de configuração | Cada variável de ambiente |
| RSS e conhecimento | Ingestão e promoção passiva de conhecimento |
| Múltiplas máquinas | Proxy reverso, OAuth 2.1 para claude.ai, solução de problemas |
| Interface Web | O painel de gerenciamento e métricas do Prometheus |
| Arquitetura | Contêineres, pipeline de recall, decisões de design |
| Especificações de tipos de memória | O modelo de armazenamento, campo a campo |
| Guias de conexão | Configuração por agente |
| Guias de implantação | macOS · Raspberry Pi · AWS · GCP · Linux + Tailscale Funnel |
Especificações de armazenamento por namespace, se você quiser saber exatamente o que é gravado no Valkey e por quem: visão geral · episódico · projeto · conhecimento · preferência · habilidade
Contribuindo
Issues e PRs são bem-vindos. O desenvolvimento acontece no Codeberg — issues e PRs lá, por favor. O OmniMem é projetado para ser estendido e o pipeline de pontuação é estruturado para que novos multiplicadores possam ser adicionados sem tocar no núcleo. Novas ferramentas MCP, tipos adicionais de namespace e backends alternativos de embedding são todas direções razoáveis.
Licença
MIT. Livre para usar, fazer fork e modificar. Sem nível empresarial, sem versão hospedada, sem amarras.
Construído por Ric Harvey @ SquareCows Ltd, uma consultoria de IA e automação para pessoas que preferem possuir suas próprias ferramentas.