feedback-memory

Configuração de Agente Autoaprendiz

Um padrão pequeno e prático para fazer um agente de IA lembrar do seu negócio e aprender com cada correção que você fizer. Sem necessidade de framework: uma pasta de arquivos da marca, seu banco de dados existente e uma tabela de feedback.

Eu administro um negócio de educação individual na Coreia dessa forma. Agentes (Claude Code, Codex) rascunham posts e respostas. Eu aprovo, edito ou rejeito pelo celular. Cada decisão vai para um banco de dados, e o próximo rascunho lê esse histórico antes de escrever uma palavra.

Este repositório contém o esquema mínimo e os prompts. O passo a passo completo é um guia gratuito de 23 páginas (link no final).

Experimente em um minuto

No seu navegador, sem instalação: https://ssap-pa.github.io/self-learning-agent-setup/ (Postgres + pgvector via PGlite e o modelo de embeddings all-MiniLM-L6-v2 via Transformers.js, tudo rodando na aba, sem chave de API).

Localmente:

git clone https://github.com/ssap-pa/self-learning-agent-setup
cd self-learning-agent-setup/demo
npm install
npm run demo

Ele inicia um Postgres em memória (PGlite + pgvector), insere três dias de feedback para uma loja fictícia de velas (uma edição, uma rejeição, uma aprovação simples) e imprime o que o agente leria antes dos próximos rascunhos. Não é necessário banco de dados nem chave de API. npm test executa os testes da mesma forma.

Day 3  new comment: "How long does shipping to Canada take for the lavender set?"
       before drafting, the agent reads:
         Feedback on similar past tasks (most similar first):
         - task: "Do you ship to Canada? Love the lavender candle" -> edited to: "We do! Canada usually takes 5-7 days." (why: don't promise speed, give the real shipping time)

Day 3  new comment: "Could you gift wrap a candle for a birthday?"
       before drafting, the agent reads:
         Feedback on similar past tasks (most similar first):
         - task: "Can you gift wrap the vanilla set for my mom?" -> rejected (why: we don't gift wrap, offer the gift note instead)

Day 3  new comment: "What wax do you use?"
       before drafting, the agent reads:
         (nothing yet: no feedback on anything similar)

A demonstração incorpora texto por hash de palavras, então "semelhante" aqui significa palavras compartilhadas. Execute EMBED=openai OPENAI_API_KEY=... npm run demo para usar embeddings reais, ou aponte Loop para seu próprio Postgres / Supabase com pg.

Use no Claude Code, Cursor ou Claude Desktop (servidor MCP)

feedback-memory é um pequeno servidor MCP construído no mesmo ciclo. Seu agente chama recall_corrections antes de rascunhar e record_decision depois que você aprovar, editar ou rejeitar. Tudo fica em um Postgres local (PGlite + pgvector) em ~/.feedback-memory, então não há nada para hospedar.

Claude Code, como plugin (a forma mais fácil). Suas regras permanentes são carregadas quando uma sessão inicia (e novamente após /clear ou compactação), e as correções passadas mais próximas são adicionadas a cada prompt por um hook, então elas se aplicam mesmo quando o Claude não chama uma ferramenta:

/plugin marketplace add https://github.com/ssap-pa/self-learning-agent-setup.git
/plugin install feedback-memory@ssap-pa

(A forma curta /plugin marketplace add ssap-pa/self-learning-agent-setup também funciona se você tiver uma chave SSH configurada para o GitHub.)

Em uma execução real com o plugin, o Claude não fez chamadas de ferramenta e ainda respondeu a um novo comentário "quanto tempo leva o envio para o Canadá?" com "Obrigado por perguntar. O envio para o Canadá geralmente leva de 5 a 7 dias úteis para o conjunto de lavanda.": o tempo de envio de uma edição passada (motivo: não prometa rapidez) e sem pontos de exclamação, de uma regra armazenada.

Claude Code, apenas servidor MCP:

claude mcp add feedback-memory -- npx -y github:ssap-pa/self-learning-agent-setup

Claude Desktop, com um clique: baixe feedback-memory.mcpb e abra. O campo de chave OpenAI é opcional.

Cursor, ou Claude Desktop manualmente (em mcpServers no JSON de configuração):

"feedback-memory": { "command": "npx", "args": ["-y", "github:ssap-pa/self-learning-agent-setup"] }

Depois diga ao agente quando usar, por exemplo, duas linhas em CLAUDE.md / AGENTS.md:

Before drafting anything I'll review, call recall_corrections with the task and follow what comes back.
When I approve, edit or reject your draft, call record_decision with my reason.

Ferramentas: recall_corrections, record_decision, add_rule (regras permanentes que sempre voltam primeiro), list_memory, forget. Defina OPENAI_API_KEY no ambiente do servidor para corresponder por significado (text-embedding-3-small); sem isso, as palavras são transformadas em hash offline (com leve stemming, então "envio" corresponde a "enviar") e apenas palavras compartilhadas correspondem. Uma pasta de banco de dados por cliente em execução (defina FEEDBACK_MEMORY_DIR se você executar vários), então instale de uma forma, não como plugin e servidor MCP separado ao mesmo tempo. npm test executa um teste de ponta a ponta via stdio, e npm run bundle compila o pacote do Claude Desktop.

Se ajudar, uma estrela no repositório ajuda outras pessoas a encontrá-lo, e uma issue sobre o que não funcionou me ajuda a corrigir.

O problema

Qualquer pessoa pode pagar pelo mesmo modelo que você usa. O que ninguém mais pode comprar é:

1. o que seu agente sabe sobre seu negócio, e
2. o registro de cada correção que você deu a ele.

A maioria das pessoas dá feedback no chat e o perde. A próxima sessão começa do zero, e você corrige "flores deslumbrantes" pela décima vez.

Camada 1: a camada de conhecimento (o que ele sabe)

Tipo	Exemplo	Onde fica
Constantes	Marca, voz, cliente, história do fundador	Arquivos Markdown em uma pasta brand/
Variáveis	Preço, estoque, assentos, agenda	Banco de dados do seu site, lido ao vivo
Conhecimento amplo	Lições, ebooks, FAQs	Mesmo banco de dados, incorporado para busca (RAG)

Regras que importam:

• Arquivos para quem você é, banco de dados para o que é verdade agora. Preços em um arquivo de texto ficam desatualizados, e o agente cita a promoção do mês passado com confiança.
• O agente só pode dizer o que sua página de administração armazena. "3 assentos restantes" exige um campo de assentos.
• Imponha no código. Uma regra que só existe em AGENTS.md pode ser ignorada. Programas que rodam sozinhos devem chamar o banco de dados e buscar diretamente.

Camada 2: o ciclo de aprendizado (como ele melhora)

1. Armazene cada aprovação (+1), rejeição (−1) e edição (0, com a correção), vinculada à execução que ela avalia.
2. Gere candidatos. Feedback repetido se torna uma regra proposta, não ativa.
3. Pontue com uma rubrica por objetivo.
4. Compare o candidato com o comportamento atual.
5. Promova ou descarte.

Mais dois detalhes que fizeram funcionar de verdade para mim:

• Regras vs. memória. "Seu tom parece robótico" sempre se aplica (regra). "Para pedidos de funeral, sem emojis" só se aplica quando a situação corresponde (memória). Memórias que se repetem são promovidas.
• Busque feedback por significado. A busca por palavras-chave perdia feedback formulado de forma diferente. Embeddings trazem correções de situações semelhantes.

E a parte humana: um bot do Telegram envia cada rascunho para meu celular com botões Aprovar / Rejeitar / Editar, e os toques caem no banco de dados de aprendizado (não apenas no log do bot). Verifique se eles realmente caem. O meu silenciosamente não armazenava aprovações no início.

O que está aqui

• schema.sql: tabelas Postgres / Supabase (runs, feedback com embeddings de situação e motivo, rules) e match_feedback() para busca por similaridade, com pgvector
• demo/loop.ts: o ciclo central em cerca de 100 linhas de TypeScript: armazene cada decisão, traga feedback de tarefas passadas semelhantes para o próximo prompt. Funciona com pg ou PGlite
• demo/demo.ts e demo/loop.test.ts: a demonstração de um minuto e os testes
• prompts.md: os prompts que uso com Claude Code / Codex para construir e verificar cada camada

Comece pequeno

• Execute um objetivo com limites baixos (o meu: 1 post e até 3 respostas por dia por duas semanas).
• Mantenha a aprovação ativa até não sobrar nada para corrigir.
• Meça compras ou inscrições, não curtidas.

Mais

• Precisa em várias máquinas ou em equipe, ou aprovações pelo celular? O plugin gratuito mantém a memória em uma pasta em uma máquina. O Self-Learning Agent Kit executa o mesmo ciclo no seu próprio Postgres / Supabase para que cada máquina e colega compartilhe uma memória, adiciona um bot do Telegram para aprovar / editar / rejeitar pelo celular (cada toque é armazenado antes de qualquer publicação), propõe regras a partir de motivos que se repetem, e envia versões Python e TypeScript da biblioteca + CLI, um servidor MCP e seu próprio plugin do Claude Code cujos hooks leem esse banco de dados compartilhado (por significado, com embeddings OpenAI), um exemplo de ponta a ponta e 28 testes ($39): https://payhip.com/b/grc25
• Prefere vídeo? Uma aula gratuita de 22 minutos onde construo esse sistema com um agente (áudio em coreano, legendas em inglês, sem conta): https://ssapable.com/courses/ai-agent?lang=en&utm_source=github&utm_medium=readme#free-preview
• Guia gratuito (23 páginas, PDF): o passo a passo completo com um exemplo prático e um plano de 7 dias: https://payhip.com/b/QHgfJ
• O livro: Just Say "Do It", um guia de 11 passos para administrar um negócio individual com agentes de IA (edição em inglês do meu curso em coreano): https://payhip.com/b/xmZvu. Pague o quanto quiser até domingo, 4 de outubro (Pacífico dos EUA), e $0 é aceitável; se você ler, uma avaliação honesta nessa página ajuda muito.
• Quer configurado para o seu negócio? Blueprint de automação feito para você: https://payhip.com/b/BzSRC

---

Texto e diagramas (este README, prompts.md, img/) © 2026 AI SSAPABLE, compartilhados sob CC BY-NC 4.0. A Licença MIT em LICENSE cobre o código: schema.sql, demo/, docs/, mcp/, hooks/, bundle/ e .claude-plugin/.