Mengram

Dê aos seus agentes de IA uma memória que realmente aprende

Website · Obter API Key · Docs · Console · Exemplos

pip install mengram-ai   # or: npm install mengram-ai

mengram try              # see what memory would know about you — local only,
                         # no account, nothing leaves your machine

from mengram import Mengram
m = Mengram(api_key="om-...")           # Free key → mengram.io

m.add([{"role": "user", "content": "I use Python and deploy to Railway"}])
m.search("tech stack")                  # → facts
m.ask("what's my tech stack?")          # → synthesized answer + citations
m.episodes(query="deployment")          # → events
m.procedures(query="deploy")            # → workflows that evolve from failures

Multilíngue nativo: pergunte em russo, chinês, espanhol, japonês — Mengram recupera e responde em 23 idiomas (embeddings multilíngues Cohere + rerank).

Instale com um único prompt (qualquer ferramenta de IA)

Cole isto no Claude Desktop, Cursor, Codex, Claude Code ou Windsurf — o agente lê nosso guia de configuração, instala o SDK, configura o servidor MCP e verifica o round-trip de ponta a ponta. Sem alternância de contexto no terminal.

Install Mengram for me. Fetch the canonical install guide at
https://mengram.io/agent-install.txt and follow it precisely.
My email is YOUR_EMAIL_HERE.

Funciona em qualquer agente com ferramentas de shell + edição de arquivos + web-fetch. Prefere fazer manualmente? Veja o guia em texto simples — ele também é estruturado para olhos humanos.

Claude Code — Memória que sobrevive a /clear E à auto-compactação

Memória persistente que sobrevive a /clear, auto-compactação, troca de máquinas e transferências de equipe — o hook SessionStart é disparado após cada compactação e reinjeta seu contexto. O resumo pode ser lossy; a memória não é.

# 1. Get a free key at https://mengram.io and save it once
mkdir -p ~/.mengram && echo '{"api_key": "om-your-key-here"}' > ~/.mengram/config.json

# 2. Install the plugin (hooks + MCP server + skill)
claude plugin marketplace add alibaizhanov/mengram
claude plugin install mengram@mengram

# 3. Skip the cold start — import your existing session history
#    (secrets are redacted on your machine before anything is uploaded)
mengram import claude-code

O que acontece:

Session Start  →  Loads your cognitive profile (fires after /clear, compaction, and restarts)
Every Prompt   →  Searches past sessions for relevant context (auto-recall)
After Response →  Saves new knowledge in background (auto-save)
Before a Bash  →  If the command matches a learned workflow with a weak record, asks you first (policy gate, CLI hooks)
Before compact →  Writes the working state down — last prompts, files edited, last commands, where Claude left off (CLI hooks)
After compact  →  Puts that state back, verbatim, next to the host's summary — and tells you so in one line

Sem salvamentos manuais. Sem chamadas de ferramenta. O Claude simplesmente sabe no que você trabalhou ontem — mesmo depois que a compactação consumiu a transcrição.

Prefere hooks gerenciados via CLI em vez do plugin? pip install mengram-ai && mengram setup faz o mesmo via mengram hook install.

A mesma memória no Codex e no Cursor

Codex e Cursor disparam os mesmos eventos de ciclo de vida, então os mesmos hooks rodam lá — uma memória para os três. mengram setup os encontra na sua máquina e instala seus hooks; ou adicione-os um a um:

mengram hook install --codex      # ~/.codex/hooks.json: session context, recall on every prompt, compaction checkpoint, auto-save + task card
mengram hook install --cursor     # ~/.cursor/hooks.json: session context, compaction checkpoint (back on the next tool call), auto-save

O Cursor não tem hook de contexto por prompt (beforeSubmitPrompt só pode permitir ou bloquear), então a recuperação no meio da conversa lá é sob demanda via ferramentas MCP; início de sessão e compactação são automáticos.

Cada fato registra qual ferramenta o escreveu e quando, e a recuperação mostra isso: deploys to Fly.io from main (codex, 2026-09-15). Cada hook também informa ao servidor em qual SO e ferramenta ele roda, para que um caminho de workspace registrado no seu Mac nunca chegue a uma sessão do Claude Code em uma máquina Linux, e um fato de configurações do Cursor nunca chegue ao Codex — esses são omitidos e contabilizados (facts_left_out_for_host).

Retome uma tarefa de onde parou — mengram resume

Quando um agente para, os hooks escrevem um cartão de tarefa para o repositório e branch: arquivos tocados, últimos comandos, o último teste executado e o commit em que rodou, além do rascunho do agente sobre a tarefa, o que está feito e o que falta. A próxima sessão naquele branch — amanhã, outro agente em outro worktree dele, outra máquina — recebe isso primeiro e é informada quando o código mudou desde a última verificação. Uma sessão em um branch sem cartão próprio (um worktree novo do Orca, por exemplo) só é informada de que cartões existem, já que o cartão de outro branch geralmente é a tarefa de outro agente; mengram resume mostra isso sob demanda:

$ mengram resume
[Mengram resume — where this task stands (2 h ago, from claude-code, branch main)]
Task (agent draft, not confirmed): prepare the Dify example for publication
Done:
  - three workflows assembled
  - save/recall round-trip checked through the API
Remaining:
  - import the workflows into Dify and check the model's answers
Last check: `python3 -m pytest -q tests/test_dify.py` → 4 passed in 0.31s
  The last check ran on 57cdde9; HEAD is now a1b2c3d (4 commits later). Its result describes the earlier state.
Files touched: examples/dify-support/workflow.yml
Sources: session 5d274778 · commit 57cdde9

mengram resume --open serve uma página local para corrigir o cartão, confirmá-lo (texto confirmado nunca é reescrito), escolher outra tarefa ou copiar o contexto para uma nova sessão. O cartão vive em ~/.mengram/resume/ e não precisa de conta; apenas o rascunho de tarefa/feito/restante usa um modelo.

Sem conta? Mantenha a memória em uma pasta

pip install mengram-ai
mengram local init ./memory --provider anthropic --api-key sk-ant-...   # or openai / ollama
mengram import claude-code --memory ./memory                             # seed it from your Claude Code sessions
mengram local map --memory ./memory --open                               # one page: who you are, what happened, what it learned
mengram hook install --memory ./memory                                   # the same four hooks, all local
mengram server --memory ./memory                                         # MCP for Claude Desktop, Cursor, any client

A pasta é a memória: uma árvore memfmt de Markdown que você possui — git faz diff dela, Obsidian a desenha, memfmt validate a verifica. Mesmos procedimentos-com-resultados da nuvem: versões, contagens de sucesso/falha por etapa, o gate de política e o gate de regressão que coloca em quarentena uma correção que quebraria outro fluxo de trabalho. Apenas extração e revisão de falha precisam de um modelo, e esse você traz. Nada expira e nada pede chave. Docs.

A busca local corresponde palavras em texto Unicode, incluindo russo; ela não usa embeddings nem traduz consultas. Múltiplas sessões do Mengram coordenam escritas com um lock de pasta e mesclam adições independentes. Edições conflitantes exigem recarregamento em vez de sobrescrever outra sessão. Cada arquivo alterado é substituído atomicamente, mas a pasta inteira não é uma transação única à prova de crash, e editores externos não participam do lock.

Por que Mengram?

Toda ferramenta de memória de IA armazena fatos. Mengram armazena 3 tipos de memória — e procedimentos evoluem quando falham.

Comece em 30 Segundos

1. Instale

pip install mengram-ai

2. Configuração — um comando faz tudo: conta, hooks do Claude Code, configs MCP para ferramentas detectadas (Cursor, Claude Desktop, Windsurf), importação de histórico e uma verificação de round-trip

mengram setup

Ou obtenha uma chave manualmente em mengram.io e export MENGRAM_API_KEY=om-...

3. Use

from mengram import Mengram

m = Mengram(api_key="om-...")

# Add a conversation — auto-extracts facts, events, and workflows
m.add([
    {"role": "user", "content": "Deployed to Railway today. Build passed but forgot migrations — DB crashed. Fixed by adding a pre-deploy check."},
])

# Search across all 3 memory types at once
results = m.search_all("deployment issues")
# → {semantic: [...], episodic: [...], procedural: [...]}

# Upload a PDF — auto-extracts memories using vision AI
result = m.add_file("meeting-notes.pdf")
# → {"status": "accepted", "job_id": "job-...", "page_count": 12}

# Poll for completion
m.job_status(result["job_id"])

// Node.js — pass a file path
await m.addFile('./report.pdf');

// Browser — pass a File object from <input type="file">
await m.addFile(fileInput.files[0]);

# REST API
curl -X POST https://mengram.io/v1/add_file \
  -H "Authorization: Bearer om-..." \
  -F "file=@meeting-notes.pdf" \
  -F "user_id=default"

npm install mengram-ai

const { MengramClient } = require('mengram-ai');
const m = new MengramClient('om-...');

await m.add([{ role: 'user', content: 'Fixed OOM by adding Redis cache layer' }]);
const results = await m.searchAll('database issues');
// → { semantic: [...], episodic: [...], procedural: [...] }

# Add memory
curl -X POST https://mengram.io/v1/add \
  -H "Authorization: Bearer om-..." \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "I prefer dark mode and vim keybindings"}]}'

# Search all 3 types
curl -X POST https://mengram.io/v1/search/all \
  -H "Authorization: Bearer om-..." \
  -d '{"query": "user preferences"}'

3 Tipos de Memória

Semântica — fatos, preferências, conhecimento

m.search("tech stack")
# → ["Uses Python 3.12", "Deploys to Railway", "PostgreSQL with pgvector"]

Episódica — eventos, decisões, resultados

m.episodes(query="deployment")
# → [{summary: "DB crashed due to missing migrations", outcome: "resolved", date: "2025-05-12"}]

Procedural — fluxos de trabalho que evoluem

Week 1:  "Deploy" → build → push → deploy
                                         ↓ FAILURE: forgot migrations
Week 2:  "Deploy" v2 → build → run migrations → push → deploy
                                                          ↓ FAILURE: OOM
Week 3:  "Deploy" v3 → build → run migrations → check memory → push → deploy ✅

Isso acontece automaticamente quando você relata falhas:

m.procedure_feedback(proc_id, success=False,
                     context="OOM error on step 3", failed_at_step=3)
# → Procedure evolves to v3 with new step added

Cada revisão orientada por falha registra qual suposição se mostrou falsa — não apenas qual etapa quebrou — e deriva uma pré-condição que acompanha o procedimento no momento da recuperação:

{
  "version": 3,
  "violated_assumption": "the build container had enough memory for a full build",
  "preconditions": ["check available memory before building"],
  "success_count": 11, "fail_count": 2
}

Um agente carregando a v3 não repete os dois erros que a produziram — e sabe o que verificar antes de confiar no fluxo de trabalho.

Ou totalmente automático — basta adicionar conversas e o Mengram detecta falhas e evolui procedimentos:

m.add([{"role": "user", "content": "Deploy failed again — OOM on the build step"}])
# → Episode created → linked to "Deploy" procedure → failure detected → v3 created

Pergunte à Sua Memória (RAG integrado)

m.ask() retorna uma resposta sintetizada com citações — não uma lista crua de fatos. O Mengram incorpora sua consulta, recupera os fatos mais relevantes e usa o Cohere Chat para escrever uma resposta fundamentada com atribuição nativa de fontes.

result = m.ask("what programming languages do I use?")

print(result["answer"])
# 'You use Python and Rust. Python is your daily language [1] and
#  Rust is your favorite [2]. You also know Java for enterprise
#  systems [3].'

for cit in result["citations"]:
    print(f'  "{cit["text"]}" → {cit["sources"][0]["fact"]}')
# "Python and Rust" → uses Python daily for backend development
# "favorite [2]"   → Rust is favorite language
# "Java"           → specializes in Java/Spring Boot

Multilíngue: pergunte em qualquer um dos 23 idiomas, obtenha uma resposta no mesmo idioma com citações que vinculam de volta aos fatos no idioma original em que foram armazenados. Recurso premium (Pro / Growth / Business).

Perfil Cognitivo

Uma única chamada de API gera um system prompt a partir de todas as memórias:

profile = m.get_profile()
# → "You are talking to Ali, a developer in Almaty. Uses Python, PostgreSQL,
#    and Railway. Recently debugged pgvector deployment. Prefers direct
#    communication and practical next steps."

Insira no system prompt de qualquer LLM para personalização instantânea.

Importar Dados Existentes

Elimine o problema do cold-start:

mengram import chatgpt ~/Downloads/chatgpt-export.zip --cloud   # ChatGPT history
mengram import obsidian ~/Documents/MyVault --cloud              # Obsidian vault
mengram import files notes/*.md --cloud                          # Any text/markdown

Integrações

mengram hook install

{
  "mcpServers": {
    "mengram": {
      "command": "mengram",
      "args": ["server", "--cloud"],
      "env": { "MENGRAM_API_KEY": "om-..." }
    }
  }
}

from langchain_mengram import (
    MengramRetriever,
    MengramChatMessageHistory,
)

retriever = MengramRetriever(api_key="om-...")
docs = retriever.invoke("deployment issues")

from integrations.crewai import create_mengram_tools

tools = create_mengram_tools(api_key="om-...")
# → 5 tools: search, remember, profile,
#   save_workflow, workflow_feedback

agent = Agent(role="Support", tools=tools)

openclaw plugins install openclaw-mengram

mengram search "deployment" --cloud
mengram profile --cloud
mengram import chatgpt export.zip --cloud
mengram hook install

{
  "mcp_servers": [{
    "type": "url",
    "name": "mengram",
    "url": "https://mengram.io/mcp/sse"
  }]
}

POST https://mengram.io/v1/add
POST https://mengram.io/v1/search

Isolamento Multi-Usuário

Uma chave de API, muitos usuários — cada um vê apenas seus próprios dados:

m.add([...], user_id="alice")
m.add([...], user_id="bob")

m.search_all("preferences", user_id="alice")  # Only Alice's memories
m.get_profile(user_id="alice")                 # Alice's cognitive profile

Cliente Assíncrono

Cliente Python não bloqueante construído sobre httpx:

from mengram import AsyncMengram

async with AsyncMengram() as m:
    await m.add([{"role": "user", "content": "I use async/await"}])
    results = await m.search("async")
    profile = await m.get_profile()

Instale com pip install mengram-ai[async].

Filtros de Metadados

Filtre resultados de busca por metadados:

results = m.search("config", filters={"agent_id": "support-bot", "app_id": "prod"})

Webhooks

Seja notificado quando memórias mudarem:

m.create_webhook(
    url="https://your-app.com/hook",
    event_types=["memory_add", "memory_update"],
)

Templates de Agentes

Clone, defina a chave de API, execute em 5 minutos:

cd examples/devops-agent && pip install -r requirements.txt
export MENGRAM_API_KEY=om-...
python main.py

Use com Agentes de IA

Mengram funciona como um backend de memória persistente para agentes autônomos. Seu agente armazena o que aprende e recupera na próxima execução — ficando mais inteligente com o tempo.

from mengram import Mengram

m = Mengram(api_key="om-...")

# Agent completes a task → store what happened
m.add([
    {"role": "user", "content": "Apply to Acme Corp on Greenhouse"},
    {"role": "assistant", "content": "Applied successfully. Had to use React Select workaround for dropdowns."},
])
# → Extracts: fact ("applied to Acme Corp"), episode ("Greenhouse application"),
#   procedure ("React Select dropdown workaround")

# Next run → agent recalls what worked before
context = m.search_all("Greenhouse application tips")
# → Returns past procedures, failures, and successful strategies

# Report outcome → procedures evolve
m.procedure_feedback(proc_id, success=False,
                     context="Dropdown fix stopped working")
# → Procedure auto-evolves to a new version

Funciona com qualquer framework de agente — CrewAI, LangChain, AutoGPT, loops personalizados. O agente apenas chama add() após ações e search() antes de decisões.

Self-Hosted (Ollama)

Quando executado localmente com Ollama, use modelos com 8B+ parâmetros e janela de contexto de 8K+. O prompt de extração tem cerca de 4.000 tokens — modelos menores podem alucinar ou misturar exemplos com dados reais.

Referência da API

Documentação interativa completa: mengram.io/docs

Cabeçalhos de Cota

Toda resposta autenticada inclui cabeçalhos de uso:

Os SDKs expõem isso via .quota:

m.search("test")
print(m.quota)  # {"add": {"used": 5, "limit": 30}, "search": {"used": 12, "limit": 100}}

Comunidade

• GitHub Issues — relatórios de bugs, solicitações de recursos
• GitHub Discussions — mostre seu caso de uso, faça perguntas
• API Docs — interface Swagger interativa
• Exemplos — modelos de agente prontos para uso

Histórico de Estrelas

Licença

Apache 2.0 — gratuito para uso comercial.