PLUR Memory Engine
Memória persistente local-first para agentes de IA compatíveis com MCP.
Documentação
PLUR — Seus agentes compartilham a mesma memória
Memória persistente e aberta para agentes de IA — local-first, custo zero, compartilhada entre ferramentas MCP (Claude Code, Codex, Cursor, Hermes, OpenClaw). A memória do seu agente são engrams em texto puro que você pode ler, corrigir e excluir — não pesos que você não pode.
plur.ai · Benchmark · Engram Spec · npm · Comparações
Benchmarks
PLUR é memória, não apenas recuperação — por isso medimos em mais de um eixo, no corpus completo, e publicamos o harness para que você possa reproduzir cada número.
Recall de recuperação — LongMemEval-S completo (N=500), R@5, totalmente local:
| Stack | R@5 | Notas |
|---|---|---|
| Somente BM25 | 92,2% | sem embedder — totalmente isolado |
| Híbrido (BGE-small, padrão de envio) | 95,6% | embedder local incluído, zero downloads |
| + BGE-reranker-v2-m3 | 97,6% | cross-encoder local, qualidade máxima — opt-in, ≈5s p50 em CPU |
Os números vêm de plur-ai/plur-bench, que é a fonte da verdade para cada figura de benchmark que a PLUR publica. Onde um número no repositório e um número do plur-bench discordam, o plur-bench vence — é o harness reproduzível, e é o que o CI verifica em regressão.
Granularidade de chunks, pontuação de documento canônico, SHA256 do corpus fixado — reproduza em plur-ai/plur-bench. Nenhuma chamada de nuvem é necessária para qualquer um desses números (um embedder de nuvem opcional, openai-3-large, atinge 97,0% híbrido). Um reranker mais rápido — ms-marco-minilm-l6 (p50≈245ms vs ≈5s do BGE em CPU) — troca um pouco de recall por latência abaixo de um segundo.
Execute você mesmo — e nos conte o que obteve. O harness é plur-ai/plur-bench: executável em CPU, sem necessidade de chave de API para o caminho local, corpus baixado automaticamente e verificado por SHA. Se você executar, adoraríamos ver seus números — abra uma issue ou discussão com seus resultados, especialmente se não corresponderem aos nossos. Reprodução independente vale mais do que qualquer número que publicamos, e teremos prazer em creditar você.
Recuperação ≠ precisão de resposta — e reportamos separadamente, nunca misturados. Precisão de resposta de ponta a ponta (avaliada por LLM) com o stack de reranker é 60,5%, versus 52,0% para despejar contexto completo no prompt e 5,5% sem memória alguma.
Impacto em tarefas de agente — mesma tarefa, com memória vs sem: Haiku + PLUR supera Opus sem ela a aproximadamente 10× menos custo; regras da casa 12–0 entre Haiku, Sonnet e Opus.
Operacional — busca local-first, custo zero, soberania de dados por design.
Mais em andamento: LoCoMo, suítes de tarefas agênticas, portabilidade entre ferramentas, correção de decaimento/contradição. Metodologia completa →
A ideia
Você corrige o estilo de codificação do seu agente na segunda-feira. Na terça, ele comete o mesmo erro. Você explica sua arquitetura no Cursor. Naquela noite, o Claude Code não tem ideia.
A PLUR resolve isso. Instale uma vez, e correções, preferências e convenções persistem — entre sessões, ferramentas e máquinas. Sua memória é armazenada como YAML simples no seu disco. Sem nuvem, sem chamadas de API, sem caixa-preta.
A parte interessante: em nosso benchmark de roteamento de ferramentas e conhecimento local, Haiku com memória PLUR superou Opus sem ela — 2,6x melhor em roteamento de ferramentas, a aproximadamente 10x menos custo. Acontece que o gargalo não é a inteligência do modelo. É o contexto.
O modelo é alugado; sua memória é sua. Troque Haiku por Opus para o que quer que seja lançado no próximo mês — o raciocínio é uma commodity que você não controla. A parte que é sua — tudo o que o agente aprendeu sobre seu trabalho, suas correções, suas convenções — não deveria viver na nuvem de outra pessoa ou estar embutida em pesos que você não pode ler. A PLUR mantém isso em arquivos simples no seu disco, em um formato aberto que você pode inspecionar, corrigir e excluir. É isso que significa possuir sua inteligência.
Instalação
Diga ao seu agente
Cole isto no seu agente de codificação (Claude Code, Cursor, Windsurf, OpenClaw):
Set up PLUR memory for me: run `npx @plur-ai/mcp init`, then check my PLUR status to confirm it works.
Prefere uma configuração guiada? plur.ai tem a configuração exata para sua ferramenta — Claude Code, Cursor, Windsurf ou OpenClaw.
Configuração manual (Claude Code)
Um comando configura tudo — armazenamento, configuração MCP e hooks do Claude Code:
npx @plur-ai/mcp init
Isso cria ~/.plur/ para armazenamento, adiciona PLUR ao seu .mcp.json e instala hooks do Claude Code para injeção automática de engrams. Os hooks também fecham automaticamente o ciclo de vida da memória: um hook SessionEnd captura um episódio de encerramento e limpa o estado da sessão quando uma conversa termina, para que a memória feche de forma limpa mesmo se o agente esquecer de chamar plur_session_end. A PLUR é instalada globalmente — um servidor MCP, um armazenamento, disponível em todos os projetos. Você só executa o init uma vez.
Para configurações multi-projeto, use domínio/escopo para separar conhecimento:
cd ~/projects/my-app
npx @plur-ai/cli init --domain myapp --scope project:my-app
Isso cria um .plur.yaml no projeto com padrões que os hooks aplicam automaticamente. Engrams aprendidos nesse projeto são marcados; o recall filtra por escopo, mas sempre inclui conhecimento global.
Defina o escopo por engram, pelo conteúdo. Escopo não é uma configuração única por sessão — cada chamada plur_learn recebe seu próprio scope, escolhido com base no que o engram se refere. Conhecimento de equipe/compartilhado vai para um escopo de equipe (ex.: group:<org>/<team>, usado pela PLUR Enterprise); detalhes de projeto para project:<name>; preferências pessoais permanecem locais. Não deixe conhecimento relevante para a equipe cair em global ao omitir o escopo — global vaza para todos os projetos e (com um armazenamento de equipe configurado) nunca chega à equipe. plur_session_start lista os escopos remotos que um token pode gravar.
Instalação global (inicialização mais rápida)
npm install -g @plur-ai/mcp
plur-mcp init
Cursor
Execute o init a partir da raiz do seu projeto — ele configura o .cursor/mcp.json do Cursor (além dos hooks do Cursor e uma regra de contexto):
npx @plur-ai/mcp init
A PLUR roda sob um perfil de ferramentas enxuto no Cursor (PLUR_TOOL_PROFILE=cursor) — o Cursor limita as ferramentas que um workspace pode expor, então a PLUR apresenta um conjunto principal curado (learn / recall / inject / status) em vez de todos os 43, com o restante acessível via plur_admin. O suporte ao Cursor foi lançado na v0.13.
Codex
npx @plur-ai/cli init --codex
Registra o servidor MCP via codex mcp add, grava hooks de ciclo de vida em ~/.codex/hooks.json e adiciona uma seção PLUR ao AGENTS.md. Detectado automaticamente quando ~/.codex/ existe.
A injeção usa busca híbrida (BM25 + embeddings) com fallback automático para BM25 se o embedder estiver lento ou indisponível. Defina PLUR_HOOK_HYBRID=0 para forçar BM25 (aplica-se também aos hooks do Antigravity; PLUR_CODEX_HYBRID é respeitado como alias). PLUR_HOOK_HYBRID_DEADLINE_MS ajusta o prazo do fallback — mantenha-o abaixo do timeout de hook do seu harness (Codex 25s, Antigravity 20s).
Uma etapa manual após a instalação: abra o Codex, execute /hooks e confie nas entradas da PLUR. O Codex registra a impressão digital de cada hook e se recusa a executar hooks não confiáveis — silenciosamente, sem aviso e com código de saída zero. Até você confiar neles, a memória simplesmente nunca carrega. plur doctor também diz isso.
Qual integração você obtém
Todo cliente MCP pode chamar as ferramentas da PLUR. Apenas alguns têm um adaptador — os hooks e o contexto sempre ativo que fazem a memória carregar automaticamente em vez de esperar que o agente pense nisso. Sem um, o recall e o aprendizado dependem inteiramente do modelo escolher chamar as ferramentas, o que degrada severamente sob pressão de contexto.
| Harness | Ferramentas | Injeção automática + aplicação |
|---|---|---|
| Claude Code | ✅ | ✅ hooks + CLAUDE.md |
| Codex | ✅ | ✅ hooks + AGENTS.md (confie em /hooks uma vez) |
| Cursor | ✅ | ✅ hooks + regras |
| OpenClaw | ✅ | ✅ plugin ContextEngine |
| Hermes | ✅ | ✅ plugin |
Antigravity CLI (agy) | ✅ | ✅ hooks + AGENTS.md |
| Windsurf, Gemini CLI, outros clientes MCP | ✅ | ❌ apenas ferramentas |
Se o seu harness estiver na última linha, cole a seção PLUR de CLAUDE.md em
seu próprio arquivo de contexto (AGENTS.md, GEMINI.md, …) como medida provisória — isso
restaura a camada de instruções, embora não a injeção automática.
Antigravity CLI (agy)
npx @plur-ai/cli init --antigravity
Grava hooks e o servidor MCP na configuração global do agy (~/.gemini/config/) e adiciona uma seção PLUR ao AGENTS.md. Detectado automaticamente quando ~/.gemini/antigravity-cli/ existe. Sem etapa de confiança — o agy executa hooks configurados na primeira invocação; basta reiniciar o agy.
O Antigravity não tem evento de início de sessão nem hook por prompt, então a PLUR conduz tudo a partir de PreInvocation: o recall por prompt é lido da transcrição da conversa, e a memória do turno é reinjetada como uma mensagem efêmera em cada invocação do modelo, para que sobreviva a chamadas de ferramenta sem se acumular no histórico.
Usuários do Gemini CLI: o Google está migrando o Gemini CLI para o Antigravity — instale agy e execute o comando acima. O próprio Gemini CLI permanece apenas com ferramentas.
OpenClaw
openclaw plugins install @plur-ai/claw
openclaw config set plur.enabled true
É isso. A PLUR funciona em segundo plano a partir daqui. Nenhuma mudança de fluxo de trabalho necessária — apenas use suas ferramentas como de costume. As correções se acumulam automaticamente.
DeepSeek Harness
dsh plugin add @plur-ai/dsh
Nativo, não uma ponte MCP. A PLUR é montada como um plugin Cordis e grava seus engrams diretamente no prompt do sistema, para que o modelo os leia da mesma forma que lê suas próprias instruções — sem chamada de ferramenta, sem ida e volta, e sem turno gasto decidindo se deve olhar. A seção é re-renderizada a cada montagem em vez de anexada, para que a memória não se acumule no contexto conforme uma sessão avança.
Cinco ferramentas (plur_recall, plur_learn, plur_forget, plur_feedback,
plur_status) ainda são registradas para quando o agente quiser alcançar a
memória deliberadamente. O escopo padrão é fechado — cada workspace obtém o seu próprio,
resolvido a partir do seu .plur.yaml.
/plur reporta o status; /plur-memory abre o visualizador de memória abaixo.
Hermes Agent
pip install plur-hermes
npm install -g @plur-ai/cli
O plugin se registra automaticamente via sistema de plugins do Hermes. Ele injeta memórias relevantes antes de cada chamada de LLM, extrai aprendizados das respostas do agente e expõe todas as ferramentas da PLUR ao agente. O Hermes delega para a CLI da PLUR.
SDK Python (LangChain, llama.cpp, scripts)
Para ambientes Python que não são Hermes:
pip install "plur-ai @ git+https://github.com/plur-ai/plur.git#subdirectory=packages/python"
npm install -g @plur-ai/cli # bridge (required)
Nota:
plur-aiainda não está no PyPI — use a instalação via git acima até que #915 seja resolvido.
from plur_ai import Plur
plur = Plur()
plur.learn("always use async generators for streaming LLM output")
results = plur.recall("streaming patterns")
context = plur.inject("write a streaming endpoint", limit=10)
plur-ai faz a ponte para o mesmo armazenamento em disco que Claude Code e OpenClaw — memória gravada a partir do Python fica imediatamente visível em todas as suas ferramentas. Veja packages/python/examples/ para exemplos de integração com LangChain e llama.cpp.
Verifique se funciona
Pergunte ao seu agente: "Qual é o meu status PLUR?" — ele deve chamar plur_status e retornar sua contagem de engrams e o caminho de armazenamento.
Leia sua memória
plur dashboard
Abre uma página local listando cada engram: o que foi aprendido, o que realmente é
recuperado e com que frequência. Somente leitura, somente loopback e servido da sua própria
máquina — nada é enviado. --port move isso, --no-open pula o
navegador. Dentro do DeepSeek Harness, a mesma página está a um /plur-memory de distância.
Disponível em inglês e 中文; segue seu navegador, ou ?lang=zh.
Veja em ação
Assim que estiver rodando, ensine algo ao seu agente uma vez:
"Sempre use
pnpmneste projeto —npm installquebra o lockfile no CI."
Inicie uma nova sessão no dia seguinte e pergunte:
You: How do I run the tests?
<plur-memory> 1 engram · project:my-api </plur-memory>
Agent: Use pnpm — you mentioned npm breaks the lockfile in CI:
pnpm test # full suite
pnpm test -- src/auth.test.ts # single file
Nova sessão. Sem lembrete. A correção estava lá.
Esse é o momento em que a PLUR compensa — o agente lembra de uma convenção de projeto que você mencionou uma vez, sem que ela esteja em nenhum arquivo que ele possa ler.
Como funciona
A PLUR tem dois primitivos de armazenamento: Engrams — conhecimento aprendido que persiste entre sessões. Cada engrama é uma afirmação tipada ("sempre use deploys blue-green", "nunca faça force-push na main") com:
- Ativação — força de recuperação que decai com o tempo (modelo ACT-R) e se fortalece no acesso. Fatos obsoletos desaparecem naturalmente da injeção sem limpeza manual.
- Sinais de feedback — classificações positivas/negativas que treinam a qualidade da injeção ao longo do tempo
- Escopo — namespace hierárquico (
global,project:myapp,cluster:prod,service:api) que controla onde o engrama se aplica - Polaridade — classificação automática de regras "faça" vs "não faça", para que restrições sejam injetadas separadamente de diretivas
- Associações — links para outros engramas, incluindo arestas de co-acesso que se formam automaticamente quando engramas são recuperados juntos
Episódios — registros de eventos com timestamp para "o que aconteceu e quando". Cada episódio captura um resumo, timestamp, atribuição de agente e canal. Use episódios para linhas do tempo de incidentes, logs de sessão e histórico operacional. Consulte por intervalo de tempo, agente ou canal.
You correct your agent → engram created → YAML on your disk
Agent fixes an incident → episode captured → timeline searchable
Next session starts → relevant engrams injected → agent remembers
You rate the result → engram strengthens or decays → quality improves
Unused engrams → activation decays → naturally fade from injection
A busca é totalmente local: BM25 (com ponderação IDF, saturação TF, normalização de comprimento) + embeddings BGE + Fusão de Rank Recíproco. Zero chamadas de API, zero custo por consulta. Metodologia de benchmark →
Plugins (OpenClaw, Hermes) capturam automaticamente aprendizados das conversas dos agentes — sem necessidade de salvamento manual. As correções do agente se tornam engramas sem que você faça nada.
Veja a especificação completa de engramas para detalhes de schema, modelo de ativação e algoritmo de injeção.
Formato aberto
O engrama é um formato aberto e versionado — não uma caixa preta. Cada engrama é YAML simples validado contra um JSON Schema publicado, gerado a partir da mesma fonte Zod que o motor usa (os schemas vivem em spec/). Leia-o, faça diff no git, escreva suas próprias ferramentas contra ele ou construa um motor diferente no mesmo formato — sua memória não está presa ao PLUR.
Uso
import { Plur } from '@plur-ai/core'
const plur = new Plur()
// Learn from a correction. The engine's read and write methods are async —
// they return promises so a `Plur` can be backed by a network store as well
// as by the default local YAML one.
await plur.learn('toEqual() in Vitest is strict — use toMatchObject() for partial matching', {
type: 'behavioral',
scope: 'project:my-app',
domain: 'dev/testing'
})
// Recall (hybrid: BM25 + embeddings, zero cost)
const results = await plur.recallHybrid('vitest assertion matching')
// Inject relevant engrams into agent context. You get context blocks ready to
// paste into a prompt plus the IDs that went into them — not the engrams
// themselves. `budget` is the ceiling in tokens; selection fills it by relevance.
const injection = await plur.inject('Write tests for the user service', {
scope: 'project:my-app',
budget: 2000
})
console.log(injection.directives) // also .constraints, .consider
console.log(`${injection.count} engrams, ${injection.tokens_used} tokens`)
// Feedback trains the system — rate anything you have an ID for, whether it came
// back from recall or went out in an injection (injection.injected_ids).
if (results[0]) await plur.feedback(results[0].id, 'positive')
// Capture an event (episode). Episode operations stay synchronous — they are
// backed by episodes.yaml, not the engram primary store.
plur.capture('Fixed CrashLoopBackOff on bee-3-4 by increasing memory limits', {
agent: 'claude-code',
channel: 'terminal'
})
// Query timeline
const incidents = plur.timeline({ agent: 'claude-code' })
// Sync across machines (use a private git remote — all engrams including private-visibility ones are pushed)
await plur.sync('git@github.com:you/plur-memory.git')
Ferramentas
| Ferramenta | O que faz |
|---|---|
plur_learn | Armazena uma correção, preferência ou convenção |
plur_learn_batch | Armazena muitos engramas em uma única chamada (deduplicação em lote + isolamento de falhas por item) |
plur_recall | Recupera memórias relevantes — híbrido (BM25 + embeddings) por padrão; mode:"keyword" para apenas BM25 |
plur_inject_hybrid | Seleciona engramas para a tarefa atual dentro do orçamento de tokens |
plur_feedback | Avalia relevância (treina a qualidade ao longo do tempo) |
plur_forget | Aposenta uma memória (a ativação decai, eventualmente é podada) |
plur_rescope | Move um engrama existente para outro escopo — pessoal → equipe, ou de volta |
plur_session_scope | Altera o escopo de escrita padrão da sessão no meio da sessão |
plur_capture | Registra um evento — incidente, resolução, marco da sessão |
plur_timeline | Consulta o histórico de episódios por tempo, agente ou canal |
plur_ingest | Extrai engramas de texto automaticamente |
plur_sync | Sincroniza via git. Remotes personal espelham tudo (use um repositório privado); remotes shared recebem apenas engramas de escopo compartilhado e não privados |
plur_status | Verifica a saúde do sistema e contagens de engramas |
plur_receipt | Relatório local e contado do que sua memória recuperou para você |
plur_outbox | Inspeciona (e tenta novamente) gravações de equipe enfileiradas enquanto o armazenamento delas estava inacessível |
A caixa de saída
Uma gravação em um escopo de equipe vai para o armazenamento remoto da equipe. Quando o armazenamento não pode ser alcançado — VPN desligada, servidor fora do ar, token expirado — o engrama não é perdido e não é descartado silenciosamente: ele é gravado localmente com metadados de fila e tentado novamente no início da próxima sessão, em plur sync, ou sob demanda.
A fila não é um diretório. Ela vive como structured_data._outbox dentro dos engramas afetados em engrams.yaml, e é por isso que precisa de um comando para ser vista:
plur outbox # what is queued, for which scope, how long, last error
plur outbox --flush # retry now
A mesma coisa está disponível para agentes como plur_outbox ({flush: true} para tentar novamente), e plur status reporta a contagem pendente. Nenhuma das superfícies imprime a URL de destino ou o token.
O recibo de memória
plur receipt (e a ferramenta MCP plur_receipt) mostram o que sua memória realmente fez — contado a partir do histórico de recuperação do próprio PLUR, nunca estimado:
Your Memory Receipt
===================
2026-07-03 .. 2026-07-22 (71 sessions)
423 times a memory you taught PLUR
was put in front of the model.
(plus 45 times an installed-pack memory)
across 71 retrievals in 71 sessions
drawing on 162 distinct engrams
MOST-RELIED-ON
34x PLUR positioning thesis across every vertical: PLUR layers …
28x Datacore app CoS architecture: reasoning layer added on to…
...
STORE HEALTH
4,517 engrams stored (you: 3,746, packs: 771)
162 retrieved at least once (4% of store)
4,355 not retrieved since 2026-07-03 (96%)
Over a short logging window a low rate is expected, not a fault —
memory is meant to be selective, and much of the store predates logging.
(Estatísticas de REUSE e ressalvas de cobertura também são mostradas; truncadas aqui por brevidade.)
É local e somente leitura, e carrega nenhum valor em dólar ou token por design: em uma assinatura, seu custo marginal de token é zero, e o valor de uma redescoberta evitada não é mensurável a partir desses dados. O recibo reporta apenas o que pode contar. A taxa de ativação é a cobertura do armazenamento sobre a janela de registro, não uma pontuação de qualidade — ela é naturalmente baixa e cai conforme você adiciona engramas. --days N estreita a janela; --json emite a forma bruta. (A ferramenta MCP plur_receipt retorna os mesmos números mais uma linha summary que carrega esse enquadramento para o agente.)
Sincronização entre dispositivos
plur.sync(remote) é git por baixo: ele faz commit do seu armazenamento de engramas e o envia para o remote que você fornecer. O que é enviado depende do tipo declarado do remote (sync.remote_type em config.yaml, ou o argumento remote_type):
personal(padrão) — seu próprio backup/espelho entre suas máquinas. O remote recebe tudo que é enviado, incluindo engramasvisibility: private: visibilidade privada significa "não compartilhe isso em um pacote", não "não espelhe isso para meus próprios dispositivos", então engramas privados intencionalmente seguem você de máquina em máquina. Por causa disso, sempre use um remote git privado (um repositório GitHub/GitLab privado, ou seu próprio servidor). O PLUR exibe umwarningno resultado da sincronização sempre que engramas privados estão presentes. Nunca aponte uma sincronização pessoal para um repositório público.shared— um remote visível para a equipe. Apenas engramas com escopo da família compartilhada (group:/project:/space:/team:/org:/public) e visibilidade não privada são enviados; engramas da família pessoal (local,global,user:*,agent:*) e engramas com visibilidade privada nunca chegam ao remote, por construção. Observe que a visibilidade padrão éprivate, então um remote compartilhado recebe apenas engramas cuja visibilidade foi definida deliberadamente — colegas de equipe recebem o que você escolheu compartilhar, nada mais. A mesma garantia cobre os arquivos de armazenamento irmãos (#686): um episódio, candidato ou registro de tensão é enviado apenas quando cada engrama que ele referencia está no conjunto de envio — registros derivados de engramas pessoais ou privados (snapshots de declaração de uma tensão, episódio de relatório de falha) permanecem locais, assim como qualquer registro que referencie um engrama que o filtro não consegue resolver.
Em ambos os modos, engramas scope: local são específicos da máquina por design (caminhos, portas locais, peculiaridades por host), então são removidos de todo commit e nunca chegam a nenhum remote. A remoção acontece no blob preparado: sua cópia de trabalho local sempre mantém todos os engramas.
Detalhes do benchmark
Recall de recuperação por categoria, de uma execução anterior no repositório — LongMemEval-S completo (N=500), totalmente local (BGE-small + BGE-reranker-v2-m3, granularidade de chunk). Seu número geral (98,0%) é anterior à medição atual do plur-bench da mesma pilha (97,6%) e não foi reexecutado por categoria; trate a forma como indicativa e a tabela principal acima como atual.
| Categoria | R@5 | R@10 |
|---|---|---|
| assistente-de-sessão-única | 100,0% | 100,0% |
| atualização-de-conhecimento | 100,0% | 100,0% |
| usuário-de-sessão-única | 98,6% | 100,0% |
| multi-sessão | 98,5% | 100,0% |
| raciocínio-temporal | 97,7% | 98,5% |
| preferência-de-sessão-única | 86,7% | 90,0% |
| geral | 98,0% | 99,0% |
Recall de recuperação (encontrar a memória certa) e precisão de resposta ponta a ponta (se o modelo então responde corretamente) são eixos diferentes — o PLUR os mede e reporta separadamente, nunca os confunde. Os números de impacto no agente acima vêm de uma execução A/B da mesma tarefa (com memória vs sem).
PLUR vs outras ferramentas de memória de agente
Mem0, Letta (MemGPT) e Zep resolvem problemas reais — uma API de memória plug-and-play (Mem0), um SO de agente autogerenciável (Letta), um grafo de conhecimento temporal (Zep). A aposta do PLUR é uma combinação que nenhum deles entrega junto:
- Texto simples que você possui — engramas são YAML legível por humanos que você pode ler,
git diff, editar e excluir de forma comprovável. Não vetores opacos, blocos de estado de agente ou nós de grafo que exigem ferramentas para inspecionar. - Local-first, custo zero — BM25 híbrido + embeddings locais, totalmente offline, sem conta de API (98% R@5 no corpus completo LongMemEval-S sem nenhuma chamada em nuvem — veja acima).
- Compartilhável em equipe via git —
plur syncé git por baixo, então a mesma memória segue você entre máquinas e entre uma equipe. A maioria das ferramentas é de usuário único local ou equipe em nuvem; o PLUR é ambos, e você mantém os dados. - Entre ferramentas — o mesmo armazenamento
~/.plur/funciona em Claude Code, Cursor, Windsurf, OpenClaw e Hermes. Sua memória não está presa a um único fornecedor. - Aprende e esquece — recuperação treinada por feedback com decaimento ACT-R e uma verificação de contradição sob demanda, não um armazenamento que cresce para sempre.
Se você precisa de uma API de memória hospedada ou um grafo de conhecimento temporal, use a ferramenta feita para isso. Se você quer memória que possa ler, possuir, compartilhar com sua equipe e mover entre ferramentas, esse é o PLUR. Detalhes lado a lado: comparações/.
O que o PLUR é — e não é
O PLUR é memória de agente — ele armazena correções, preferências, convenções e decisões arquiteturais que um agente de IA aprende durante sessões de trabalho, e as injeta de volta quando são relevantes.
O PLUR não é um mecanismo de busca de propósito geral, um indexador de código ou um substituto para ferramentas de inteligência de código. Ele não analisa ASTs, navega hierarquias de classes ou busca em seus arquivos de origem. Se você precisa de busca ciente de código (tree-sitter, recursos de language server, busca de símbolos), ferramentas como claude-mem ou a busca integrada do seu IDE são a escolha certa.
Os dois são complementares:
| PLUR | Ferramentas de inteligência de código | |
|---|---|---|
| Armazena | Conhecimento aprendido (engramas) + linha do tempo de eventos (episódios) | Estrutura de código, símbolos, definições |
| Busca | Recall de engramas (BM25 + embeddings sobre memória) | Travessia de AST, busca de símbolos, busca semântica de código |
| Aprende | De correções de agentes, feedback, padrões de uso | De análise estática de código-fonte |
| Captura | Extrai automaticamente aprendizados de conversas (via plugins) | N/A |
| Decai | Sim — memórias não usadas desaparecem (modelo ACT-R) | Não — o índice de código reflete o estado atual |
| Linha do tempo | Episódios rastreiam o que aconteceu e quando (incidentes, correções, decisões) | Apenas log do git |
| Entre ferramentas | Qualquer cliente MCP (Claude Code, Cursor, Windsurf, OpenClaw, Hermes) | Tipicamente vinculado a uma ferramenta |
Embora a busca seja uma parte central do PLUR (encontrar o engrama certo para injetar), os alvos da busca são sempre engramas — não arquivos, não código, não documentos. A busca híbrida do PLUR (BM25 + embeddings + RRF) é otimizada para afirmações curtas em linguagem natural, não para código-fonte.
Pacotes
| Pacote | Descrição |
|---|---|
@plur-ai/core | Mecanismo de engramas — aprender, recordar, injetar, buscar, decair |
@plur-ai/mcp | Servidor MCP para Claude Code, Cursor, Windsurf |
@plur-ai/claw | Plugin OpenClaw ContextEngine |
@plur-ai/cli | CLI — plur learn / recall / inject / status |
@plur-ai/dsh | Plugin DeepSeek Harness — engramas no prompt, sem chamada de ferramenta |
@plur-ai/opencode | Plugin opencode — engramas no prompt, sem chamada de ferramenta |
@plur-ai/migrate | Migrações de armazenamento, enviadas com a versão para a qual migram |
plur-hermes | Plugin Hermes Agent (Python, via ponte CLI) |
plur-ai | SDK Python — learn/recall/inject para LangChain, llama.cpp, scripts |
plur-langchain | Adaptador LangChain BaseMemory + BaseChatMessageHistory |
packages/ui é interno — as páginas do visualizador de memória, empacotadas na CLI e
no plugin DeepSeek Harness em vez de publicadas. Não está no npm.
Arquitetura
@plur-ai/core
├── engrams.ts Engram CRUD + YAML persistence
├── episodes.ts Episode capture + timeline queries
├── fts.ts BM25 with IDF, TF saturation (k1/b), length normalization
├── embeddings.ts BGE-small-en-v1.5, 384-dim, local ONNX
├── hybrid-search.ts Reciprocal Rank Fusion
├── inject.ts Context-aware selection + spreading activation
├── decay.ts ACT-R activation decay
├── secrets.ts Secret detection (API keys, passwords, tokens)
├── sync.ts Git-based sync + file locking (O_EXCL)
├── storage.ts Path detection + YAML I/O
└── storage-indexed.ts Optional SQLite read index
@plur-ai/mcp Wraps core as MCP tools
@plur-ai/claw OpenClaw ContextEngine hooks (assemble/compact/afterTurn)
plur-hermes Python plugin for Hermes Agent (auto inject/learn)
plur-ai Python SDK — direct learn/recall/inject for scripts and frameworks
Armazenamento
Tudo é YAML simples. Abra, leia, edite.
~/.plur/
├── engrams.yaml # learned knowledge (source of truth)
├── episodes.yaml # session timeline
├── config.yaml # settings
└── engrams.db # optional SQLite read index (auto-generated)
PLUR_PATH substitui o local padrão.
A indexação está ativada por padrão (index: true) e o backend é escolhido com base no
tamanho do seu armazenamento, então normalmente não há nada para configurar:
| Tamanho do armazenamento | Backend | O que responde a uma consulta |
|---|---|---|
| abaixo de 5.000 engramas | yaml | BM25 em memória + cosseno exato |
| 5.000 e acima | pglite | Postgres embutido + pgvector |
| 50.000 e acima | postgres | um servidor Postgres para o qual você aponta — BM25 em SQL; pontuações de recall semântico em memória (veja abaixo) |
O YAML permanece como fonte da verdade em todos os níveis, exceto postgres (ADR-0001,
ADR-0005) — o índice é um cache que se reconstrói automaticamente, e você pode excluí-lo
a qualquer momento. Defina backend: em config.yaml para fixar um nível explicitamente.
Uma ressalva sobre o nível postgres, declarada aqui porque é a linha de destaque
desta tabela: o core não grava embeddings em um armazenamento primário Postgres
(emenda ADR-0005). O recall por palavra-chave/BM25 é executado em SQL, mas engram_embeddings
permanece vazio a menos que sua implantação o preencha, então o recall semântico e híbrido
recorre ao carregamento de engramas e à pontuação em memória — resultados corretos, ao
custo O(N) que este nível evita de outra forma. O adaptador informa isso uma vez na
inicialização do esquema; vectorIndex: 'exact' reconhece e silencia.
sqlite (engrams.db, via better-sqlite3) é o índice legado e não é mais
selecionado automaticamente.
Requisitos
- Node.js 18+
- Mínimo de 2GB de RAM — o modelo de embeddings (runtime ONNX) precisa de ~1GB para instalação. Em servidores com menos RAM, os embeddings são ignorados e a busca recorre à correspondência de palavras-chave BM25.
Desenvolvimento
git clone https://github.com/plur-ai/plur.git
cd plur
pnpm install && pnpm build && pnpm test
~3500 testes em ~200 arquivos. pnpm test:watch para desenvolvimento.
Contribuindo
- Relatórios de bugs — issue com etapas de reprodução
- Solicitações de recursos — issue descrevendo o caso de uso
- Código — fork, branch, PR. Testes obrigatórios.
- Integrações — construa suporte PLUR para outras ferramentas
Antes de enviar: pnpm test passa, pnpm build é bem-sucedido, sem novas dependências externas no core sem discussão.
Convenções: TypeScript, validação Zod, Vitest, sem APIs externas no core, armazenamento YAML, busca de custo zero por padrão.
Licença
Apache-2.0