AgenticMind

---

"Não é 'armazenamento de memória para um agente'." AgenticMind é o substrato para o qual um agente aponta quando precisa de respostas em que pode confiar, um rastro que pode auditar e uma base de conhecimento que se acumula.

A maioria da memória de agentes é um armazenamento vetorial com save() e search(). Isso compra recall difuso e zero responsabilidade: você não consegue dizer por que uma resposta voltou, se está atualizada ou se uma fonte sequer a suporta. AgenticMind trata o conhecimento como um substrato de primeira classe, auditável e auto-melhorável — e o expõe a qualquer agente via Model Context Protocol.

✨ Por que AgenticMind

• 📌 Com citação obrigatória — cada afirmação em uma resposta está vinculada a uma fonte numerada. Sem fonte, sem afirmação.
• 🔍 Totalmente auditável — um rastro de porquê reproduzível para cada resposta: o que foi recuperado, classificado e usado.
• ♻️ Auto-melhorável — respostas validadas são promovidas de volta ao corpus por um loop de acumulação controlado por juiz, impulsionado por sinais programáticos (não por polegares humanos).
• 🧩 Recuperação em camadas — trechos → cartões de fatos tipados → grafo de conhecimento; vetor híbrido + texto completo, ciente de recência.
• 🔐 Seguro por construção — tokens MCP com escopo e privilégio mínimo, autenticação com falha fechada, proteções na entrada e na saída.
• 🐘 Um único armazenamento — Postgres + pgvector carrega vetores, texto completo, o grafo (CTE recursivo) e a fila durável. Sem Redis, sem Neo4j, sem proliferação de bancos vetoriais.

🔧 Como funciona

flowchart TD
  A["🤖 Agent"] -->|"MCP request"| R["Tiered retrieval<br/>pgvector + full-text + graph"]
  R --> Y["Citation-enforced synthesis"]
  Y -->|"grounded answer + [citations]"| A
  Y --> T[("Replayable why-trace")]
  Y -->|"programmatic signals"| L["Judge-gated compounding loop"]
  L -->|"promotes validated knowledge"| R

Uma solicitação chega via MCP → o mecanismo recupera em três camadas → sintetiza uma resposta onde cada afirmação cita uma fonte → registra um rastro reproduzível → e alimenta sinais programáticos em um loop que promove conhecimento validado de volta ao corpus.

🎬 Veja funcionar

Uma chamada real de kl_ask_global contra um corpus semeado com o Agentic Product Standard. A pergunta tem deliberadamente duas metades — uma que o corpus pode responder, outra que não pode:

// → kl_ask_global
{ "question": "When should I use a multi-agent architecture instead of a single agent,
                and what must every agent ship with according to the standard?" }

// ← response (trimmed)
{
  "answer": "The provided sources do not specify when to use a multi-agent architecture
             versus a single agent. … According to the Agentic Product Standard, every
             agent must ship with a written Agent Contract [1]. This contract must cover
             ownership, forbidden actions, acceptance criteria, failure modes, escalation
             rules, and logging requirements [1].",
  "citations": [
    { "number": 1, "title": "Agent Contract requirement",
      "materialId": "ba44971b-…", "score": 0.46, "origin": "chunk" }
  ],
  "model": "google/gemini-3.1-flash-lite-preview",
  "retrievalMs": 606, "generationMs": 890,
  "phases": [ {"phase":"embed","ms":552}, {"phase":"retrieve","ms":37},
              {"phase":"synth","ms":890}, {"phase":"output_filter","ms":2} ],
  "telemetryId": "cc942e54-…"
}

Veja o que não aconteceu. A metade que o corpus não conseguiu suportar, o modelo recusou-se a responder — "as fontes fornecidas não especificam…" — em vez de inventar. A metade que ele conseguiu suportar está vinculada a uma citação numerada que você pode abrir. E cada resposta vem com um rastro de porquê (phases, model, telemetryId) que você pode reproduzir. Essa é toda a proposta em uma chamada: sem fonte, sem afirmação — e um recibo para cada resposta.

🆚 Como é diferente

	RAG simples / SDKs de memória	AgenticMind
Respostas fundamentadas	às vezes	com citação obrigatória + verificação posterior
Rastro de porquê por resposta	✗	rastro de decisão completo
Corpus auto-melhorável	✗	loop de acumulação (controlado por juiz)
Verificação relacional	✗	módulo de grafo
Executa em	varia	Postgres + pgvector (principal)

✅ Use quando / 🚫 procure outra coisa quando

Use AgenticMind quando:

• Seu agente deve responder a partir de fontes confiáveis, e cada afirmação precisa de uma citação.
• Você precisa de um rastro de porquê reproduzível e um único status (suportado / parcial / não suportado / conflitante / precisa_revisão) no qual você pode controlar um agente.
• Fontes discordantes ou desatualizadas devem ser expostas, não resolvidas silenciosamente.
• Você quer auto-melhoria governada — não mutação autônoma silenciosa de memória.
• Você precisa de auto-hospedagem (somente Postgres) e acesso nativo MCP (Claude Code, Cursor, LangGraph, OpenAI/Claude Agent SDK, agentes personalizados).

Procure outra coisa quando:

• Você só precisa de memória de chat personalizada simples (use um SDK de memória).
• Você quer uma API hospedada / UI sem código hoje — AgenticMind é infraestrutura auto-hospedada.
• Você precisa de SSO / SOC2 pronto para uso (veja o modelo de segurança para o que existe).
• Você está otimizando para o protótipo mais rápido, não para produção responsável.

🛠 Superfície do agente (MCP)

Um serviço headless (apps/server) expõe o mecanismo como ferramentas MCP via HTTP transmissível, com autenticação bearer por token com falha fechada (com escopo e privilégio mínimo):

Ferramenta	Escopo	Propósito
kl_search	knowledge:read	busca semântica / por palavras-chave de passagens
kl_ask_global	knowledge:read	resposta sintetizada + citações + um status controlável (opcional intent/facts)
kl_get_material	knowledge:read	buscar um material por id
kl_graph_neighbors	knowledge:read	materiais relacionados via grafo de conhecimento
kl_ingest	knowledge:write	adicionar texto (dividido em trechos, incorporado, destilado em cartões, extraído para o grafo)
kl_forget	knowledge:admin	excluir um material + todos os trechos/cartões/grafo derivados (inverso da ingestão)
kl_signal	knowledge:signal	emitir um sinal programático de acumulação sobre uma resposta anterior
mem_recall	memory:read	recuperar crenças (privadas ∪ compartilhadas); semântico ou viagem no tempo asOf
mem_write	memory:write	registrar uma crença na memória privada (bitemporal, ciente de revisão)
mem_forget	memory:write	retratar uma de suas próprias crenças (suave, bitemporal)

Veja O que conta como conhecimento para o contrato de Unidade de Conhecimento (o que pode se tornar conhecimento armazenado), Avaliações e limites para o que medimos e o que não afirmamos, docs/knobs.md para os ajustes opcionais de qualidade de resposta (fidelidade Tier-B, fontes contestadas, política de resposta, confiança na fonte) e o modelo de segurança (autenticação com falha fechada, RLS por locatário, análise da tríade letal, cadeia de suprimentos).

Não há frontend — os únicos consumidores são agentes via MCP. A lógica das ferramentas é agnóstica de framework em packages/shared/src/lib/knowledge/mcp-tools.ts; o host é um manipulador fetch padrão Web de ~60 linhas servido por Node ou Bun.

🚀 Início rápido

Execute — sem clone (~1 min)

Requer Docker (Compose v2.23+) e uma chave compatível com OpenAI. Um comando puxa as imagens publicadas, gera segredos, sobe Postgres + servidor + worker e imprime uma configuração MCP pronta para colar — sem clone de repositório, sem cunhagem de token:

OPENAI_API_KEY=sk-... sh -c "$(curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/quickstart.sh)"

O endpoint MCP sobe em http://localhost:3000/mcp, autenticado com um único bearer estático (MCP_API_KEY, gerado automaticamente). Aponte Claude Code / Cursor para ele com o cabeçalho Authorization: Bearer <MCP_API_KEY>.

Embeddings rodam localmente por padrão — um modelo multilíngue, offline e sem chave (bge-m3) é baixado no primeiro uso, então a recuperação não precisa de chave em nuvem. Apenas a etapa de síntese precisa de um modelo de chat: OPENAI_API_KEY para OpenAI (o padrão), ou aponte CHAT_BASE_URL para qualquer endpoint compatível com OpenAI — um Ollama ou vLLM local.

A imagem Docker publicada lê OPENAI_API_KEY e a mapeia para o CHAT_API_KEY do servidor internamente; o caminho a partir do código-fonte abaixo define CHAT_API_KEY diretamente em .env.local — mesmo segredo, apenas nomeado para cada ponto de entrada.

Prefere ler antes de executar? A mesma coisa, explícito (apenas o drop-in deploy/, sem clone completo):

mkdir agenticmind && cd agenticmind
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/.env.example       -o .env.example
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/gen-secrets.sh     -o gen-secrets.sh && chmod +x gen-secrets.sh
./gen-secrets.sh                   # writes DB password + MCP_API_KEY into .env
# set OPENAI_API_KEY in .env, then:
docker compose up -d

A partir do código-fonte (desenvolvimento e contribuição)

Requer Docker e Node ≥22.18 (ou Bun ≥1.3) — o servidor e o worker rodam em Node ou Bun puro.

git clone https://github.com/Moai-Team-LLC/AgenticMind.git
cd AgenticMind
cp .env.example .env.local         # set AUTH_SECRET (+ a chat key OR local Ollama)
./setup.sh                         # picks npm or bun, starts Postgres, runs migrations
npm run dev                        # headless MCP server on :3000  (or: bun run dev)

Verifique a compilação com npm run check (typecheck + testes) — bun run check também funciona.

Em uma configuração de desenvolvimento a partir do código-fonte, a rota /mcp tem falha fechada e aceita um JWT HS256 bearer typ="mcp" (em vez da chave estática de implantação). O servidor headless não vem com UI de administração — cunhe uma com o script de emissão (ele lê DATABASE_URL + AUTH_SECRET do seu .env.local):

npm run issue-token -- --label "claude-code" --ttl-days 365   # or: bun run issue-token --label …
# prints the bearer on the last line — capture it, it is not stored in plaintext

Então aponte um cliente MCP para http://localhost:3000/mcp com esse token como cabeçalho Authorization: Bearer …. (Lint adicionalmente requer Node ≥22.18 — veja .nvmrc.)

Nota. O Postgres Docker local não tem TLS, então .env.example envia DATABASE_SSL=false e DATABASE_URL na porta do host 5435. Para Postgres gerenciado (Supabase, RDS, …) que exige SSL, defina DATABASE_SSL=true.

🧱 Estrutura

packages/shared/src/lib/knowledge/        ← the tiered engine (the product)
packages/shared/src/lib/ai/               ← chat + embeddings (provider-agnostic; local embeddings by default)
packages/shared/src/database/             ← Drizzle schema + queries (Postgres + pgvector)
apps/server/src/{index,mcp}.ts            ← headless MCP host, Node or Bun (agent surface)
apps/worker/src/jobs/knowledge-feedback/  ← Postgres-scheduled compounding sweep

Notas de arquitetura. Agente primeiro e somente Postgres: o grafo vive atrás de uma interface GraphStore (travessia CTE recursiva no Postgres, sem serviço extra), a acumulação é impulsionada por sinais programáticos, os tokens MCP têm escopo de privilégio mínimo, o principal do agente é enxuto e o host é um servidor HTTP headless Node/Bun. A recuperação é multilíngue por padrão — embeddings locais bge-m3 cobrem muitos idiomas com zero chaves; a busca de texto completo usa a configuração simple agnóstica de idioma (configurável por implantação).

🌐 O ecossistema AgenticProduct

Um padrão e cinco implementações de referência que você pode executar — juntos eles fecham o loop que todo agente de produção precisa: executar → lembrar → medir, com segurança como um plano de garantia transversal.

	Projeto	Função
📐	agentic-product-standard	O contrato — princípios, a escada de autonomia, as camadas de harness e a disciplina de avaliação (além de um conjunto de habilidades para Claude Code).
⚙️	AgenticOps	Runtime e operações — manifestos implantáveis, agendamento, um backlog durável, um runner limitado e saúde da frota.
🧠	AgenticMind (este repositório)	Conhecimento e memória — auditável, auto-melhorável, com citação obrigatória, via MCP; somente Postgres.
📈	AgenticPerformance	Avaliações e observabilidade — rastros OTel, avaliações de conjunto dourado com portão de CI, clusters de falhas e o loop de melhoria.
🌉	AgenticGateway	Plano de modelo e custo — uma chave, roteamento medido, tetos, cache, evidência.
🛡️	AgenticAssurance	Segurança e garantia — red-team em qualquer agente (OWASP Agentic + MITRE ATLAS), um grafo de fluxo tóxico e saída SARIF.

Como eles se compõem. AgenticOps executa a frota, AgenticMind dá aos agentes conhecimento e memória auditáveis, e AgenticPerformance mede cada execução com rastros e avaliações — fechando o loop executar → lembrar → medir. AgenticGateway é o plano de modelo pelo qual toda chamada de LLM nesse loop passa — uma chave, roteamento medido por avaliação, tetos de custo — e AgenticAssurance faz red-team em qualquer agente no loop, com toda a pilha em conformidade com o agentic-product-standard.

Veja o estudo de caso AgenticMind do padrão para um mapa camada por camada de como este repositório implementa o cânone.

🤝 Contribuição e licença

Contribuições são bem-vindas — veja CONTRIBUTING.md. Licenciado sob Apache-2.0.