Frinus

Servidor MCP (Model Context Protocol) que expõe 70 ferramentas abrangendo memória cognitiva, memória de trabalho, sessões, agentes, a hierarquia de conhecimento L0–L3, tarefas de orquestração e pipelines de treinamento. O servidor utiliza stdio e é consumido pelo Claude Desktop, Claude Code, OpenCodex e qualquer cliente compatível com MCP.

GitHub

Documentação

Servidor MCP Frinus

φρήν + νοῦς — Dá ao seu agente Claude memória cognitiva e de longo prazo, com suporte da plataforma Frinus.

frinus-mcp é um servidor MCP (Model Context Protocol). Ele é a ponte entre seu cliente MCP — Claude Code, Cursor ou Claude Desktop — e a plataforma Frinus hospedada em https://frinus.rdxsec.com.br.

Ele não roda sozinho. Não armazena nada localmente: cada chamada de ferramenta é encaminhada via HTTPS para sua conta Frinus. Então, antes de fazer qualquer coisa útil, você precisa de duas coisas:

uma conta Frinus (gratuita, sem cartão), e
uma chave de API Frinus (sk-frinus-...).

Com isso em vigor, o servidor expõe 70 ferramentas que abrangem memória cognitiva, memória de trabalho, sessões, agentes, a hierarquia de conhecimento L0–L3, tarefas de orquestração e pipelines de treinamento. Ele fala stdio e funciona com qualquer cliente compatível com MCP.

Versão: 3.4.1
Ferramentas: 70 (veja a Referência de Ferramentas)
Plataforma: https://frinus.rdxsec.com.br (SaaS hospedado — o backend com o qual este servidor se comunica)
Pacote npm: frinus-mcp

Como tudo se encaixa

+-------------------+        +--------------+        +----------------------------+
| Your MCP client   | stdio  | frinus-mcp   | HTTPS  | Frinus platform            |
| (Claude Code,     | <----> | (this server,| <----> | frinus.rdxsec.com.br       |
|  Cursor, Desktop) |        |  via npx)    |        | (your memories live here)  |
+-------------------+        +--------------+        +----------------------------+

O servidor valida sua chave de API junto à plataforma na inicialização, resolve sua conta + organização e roteia cada chamada de ferramenta para lá. Sem chave de API → ele se recusa a iniciar.

Regra Zero — MCP é obrigatório

O MCP Frinus é a memória de longo prazo, a identidade e a inteligência do agente. Sem ele, o modelo não tem estado entre sessões. Todo agente Claude que se integra ao Frinus deve:

Verificar se as ferramentas MCP estão acessíveis no início da conversa (ex.: session_start, memory_search, search_with_attention).
Se inacessíveis, exibir o aviso ao usuário: "MCP Frinus não está conectado. Os recursos de memória de longo prazo estão indisponíveis."
Executar o protocolo BOOT (P1) antes de responder qualquer coisa que não seja uma saudação trivial.
Persistir aprendizados via memory_store antes de encerrar sessões produtivas.

O conjunto completo de protocolos vive no CLAUDE.md global (organização Frinus), resumido abaixo em Os 7 Protocolos.

Antes de começar — conta + chave de API

Você precisa de uma conta Frinus e uma chave de API. Ambos são gratuitos.

1. Crie uma conta gratuita

Cadastre-se em https://frinus.rdxsec.com.br. O plano Free (R$0) é suficiente para começar:

100 memórias
20 consultas/dia
sem necessidade de cartão de crédito

2. Gere uma chave de API

Depois de logado, abra as configurações da sua conta em Settings → API Keys e crie uma nova chave. Você receberá um valor com o formato:

sk-frinus-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copie agora — por segurança, ela é exibida apenas uma vez. Esse valor vai para a variável de ambiente FRINUS_API_KEY abaixo. Trate-a como uma senha; nunca a envie para um repositório.

Primeiros passos (do zero à primeira memória)

Cinco minutos, quatro etapas.

Etapa 1 — Crie sua conta

Cadastre-se em https://frinus.rdxsec.com.br (plano Free, sem cartão). Veja acima.

Etapa 2 — Gere sua chave de API

Settings → API Keys → criar. Copie o valor de sk-frinus-.... Veja acima.

Etapa 3 — Adicione o servidor ao seu cliente

Você não instala nada — npx busca e executa o pacote sob demanda. O único valor que você precisa fornecer é sua chave de API; as URLs da plataforma já usam produção por padrão.

Claude Code (uma linha):

claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest

Cursor / Claude Desktop / qualquer cliente (JSON de configuração):

{
  "mcpServers": {
    "frinus": {
      "command": "npx",
      "args": ["-y", "frinus-mcp@latest"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-..."
      }
    }
  }
}

Locais dos arquivos de configuração:

Claude Code: ~/.claude.json, em mcpServers.
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / ~/.config/claude/claude_desktop_config.json (Linux). Ou use a extensão de um clique .mcpb e apenas cole sua chave de API.
Cursor: ~/.cursor/mcp.json, em mcpServers.

Reinicie o cliente para que ele reconheça o novo servidor.

Substitua sk-frinus-... pela chave real da Etapa 2. Normalmente você define apenas FRINUS_API_KEY — toda URL de backend já usa a plataforma hospedada por padrão. Veja Variáveis de Ambiente para a lista completa e a substituição para self-host.

Etapa 4 — Valide com sua primeira memória

No seu cliente, peça ao agente para armazenar e recuperar algo:

Store this in Frinus memory: "Our staging DB is reset every night at 02:00 UTC."

depois, na mesma sessão ou em uma posterior:

What time does our staging DB reset?

Nos bastidores, o agente chama memory_store e depois memory_search / search_with_attention. Se a recuperação retornar, a ponte está ativa. Você pode confirmar que a mesma memória aparece no aplicativo web em https://frinus.rdxsec.com.br.

Variáveis de Ambiente

No uso normal, você define apenas FRINUS_API_KEY. As URLs de serviço já apontam para a plataforma hospedada — deixe-as como estão, a menos que você use self-host (veja Avançado — self-host).

Variável	Padrão (plataforma hospedada)	Descrição
`FRINUS_API_KEY`	obrigatória	Sua chave de API pessoal (`sk-frinus-...`). Resolve conta + organização na inicialização.
`MEMORY_SERVICE_URL`	`https://frinus-memory.rdxsec.com.br`	URL base do Memory Engine
`FRINUS_CP_URL`	`https://frinus-api.rdxsec.com.br`	URL base do Control Plane (conta, organizações, chaves de API, cobrança)
`AGENT_SERVICE_URL`	`https://frinus-agents.rdxsec.com.br`	URL base do Agent Service (agentes, invocação, habilidades)
`FRINUS_MEMORY_API_KEY`	—	Fallback legado para `FRINUS_API_KEY`

Na inicialização, o servidor valida a chave de API junto à plataforma e resolve sua organização + usuário logado. Se a validação falhar, ele aborta com [FATAL] para que o cliente exiba o erro — verifique novamente a chave em Settings → API Keys.

Os 7 Protocolos

Protocolo	Quando	Ferramentas	Propósito
P1 — BOOT	Início de toda sessão	`session_start`, `working_memory_get`, `search_with_attention`	Carregar identidade + estado recente + contexto relevante
P2 — CONSULT	Antes de qualquer ação	`search_with_attention`, `session_context`, `memory_reinforce`, `memory_weaken`	Recuperar, avaliar e reforçar memórias relevantes
P3 — PLAN	Ao planejar uma tarefa	`memory_store(procedural)`, `working_memory_add`, `stream_capture`	Persistir planos, estado de trabalho e decisões arquiteturais
P4 — CAPTURE	A cada 2–3 interações	`heartbeat_tick`, `working_memory_add`, `memory_store(episodic)`, `stream_capture`	Registro contínuo de progresso, bugs e padrões
P5 — LEARN	Novo conhecimento	`training_teach`, `training_qa`, `training_stats`, `stream_process`, `sleep_run`	Ensinar fatos/procedimentos e executar ciclos de consolidação
P6 — AUDIT	Manutenção	`consolidation_detect_conflicts`, `consolidation_resolve_conflict`, `consolidation_detect_redundant`, `hierarchy_consolidate`	Detectar conflitos, redundância e consolidar memórias
P7 — CLOSE	Fim da sessão	`session_summary`, `stream_process`, `memory_store`, `hierarchy_consolidate`, `session_end`	Resumir, promover itens do stream, persistir aprendizados

Os scripts detalhados dos protocolos vivem no CLAUDE.md do agente. Trate a tabela acima como o contrato que todo agente integrado ao Frinus deve respeitar.

Referência de Ferramentas

70 ferramentas agrupadas por domínio. Cada ferramenta retorna conteúdo de texto; os payloads seguem a especificação MCP Tool. Os schemas JSON completos estão em src/tools/definitions.ts.

Memória (7)

Memória cognitiva de longo prazo: episódica (o que aconteceu), semântica (o que eu sei), procedural (como fazer as coisas).

Ferramenta	Descrição
`memory_store`	Criar uma memória. `agent_id`, `content` obrigatórios. `memory_type` ∈ {episodic, semantic, procedural}. `scope` ∈ {user, agent, universe, organization}. `importance` 0–1.
`memory_search`	Busca por similaridade semântica. Filtros: `agent_id`, `memory_types`, `limit`.
`memory_get`	Buscar uma memória por `memory_id` (conteúdo completo, metadados, relevância).
`memory_list`	Listar memórias de um `agent_id` com filtro opcional de tipo.
`memory_delete`	Excluir permanentemente uma memória por `memory_id`.
`memory_reinforce`	Aumentar a relevância de uma memória útil (`memory_id`, `boost` 0–1, padrão 0.1).
`memory_weaken`	Penalizar uma memória desatualizada (`memory_id`, `penalty` 0–1, padrão 0.2).

Memória de Trabalho (3)

Estado de curto prazo, vinculado ao contexto. Lei de Miller: máximo de 7 itens por contexto, o mais antigo é removido automaticamente. TTL padrão de 30 min (máx. 2 h).

Ferramenta	Descrição
`working_memory_get`	Carregar o estado atual de um contexto. Sempre chamar no início da tarefa.
`working_memory_add`	Persistir o estado atual. Formatos de contexto: `agent:{uuid}`, `universe:{uuid}`, `organization:{uuid}`.
`working_memory_clear`	Remover todos os itens de um contexto.

Sessões (5)

Sessão = contêiner lógico para streams, memória de trabalho e captura.

Ferramenta	Descrição
`session_start`	Iniciar uma sessão para um agente. Retorna `session_id`. Suporta `parent_session_id` para herança de subagentes.
`session_end`	Encerrar uma sessão e finalizar seu resumo.
`session_context`	Recuperação combinada de trabalho + longo prazo, aprimorada com tópicos de sessão extraídos.
`session_summary`	Gerar um resumo estruturado (decisões, aprendizados, itens pendentes).
`session_clear`	Limpar o estado de trabalho de uma sessão sem encerrá-la.

Stream (4)

Pipeline de captura contínua. Os itens são agrupados, pontuados e os importantes são promovidos a memórias permanentes.

Ferramenta	Descrição
`stream_capture`	Registrar uma entrada / saída / nota interna vinculada a uma sessão.
`stream_get_session`	Reproduzir todos os itens capturados de um `session_id`.
`stream_get_recent`	Itens recentes do stream entre sessões (filtráveis).
`stream_process`	Promover itens pendentes para memória de longo prazo (gatilho manual; o agendador também executa a cada 5 min).

Contexto e Atenção (2)

Ferramenta	Descrição
`memory_get_context`	Construir uma janela de contexto limitada por tokens para uma descrição de tarefa.
`search_with_attention`	RAG com ponderação ciente do tipo de tarefa. `task_type` ∈ {implementation, debug, deploy, documentation, review} orienta os pesos de memory_type.

Usuários (2)

Ferramenta	Descrição
`user_register`	Registrar um usuário no sistema de memória (idempotente).
`user_get_context`	Recuperar memórias combinadas do usuário e contexto do tenant.

Manutenção (2)

Ferramenta	Descrição
`heartbeat_tick`	Tick barato para um agente — orienta o decaimento de relevância e consolidação leve.
`sleep_run`	Acionar um ciclo de sono. `phases` ⊆ {evaluation, forgetting, consolidation, relevance}. Espelha os sonos normal/profundo do agendador.

Consolidação (3)

Ferramenta	Descrição
`consolidation_detect_conflicts`	Apresentar memórias candidatas em conflito acima de um limite de similaridade.
`consolidation_resolve_conflict`	Manter uma memória e substituir a outra com uma nota de resolução escrita.
`consolidation_detect_redundant`	Encontrar quase duplicatas prontas para mesclagem ou remoção.

Hierarquia de Memória (2)

Ferramenta	Descrição
`hierarchy_consolidate`	Consolidar várias memórias relacionadas em uma memória-resumo de nível superior.
`hierarchy_get_tree`	Inspecionar a árvore de consolidação de uma memória raiz.

Agentes (6)

CRUD de agentes + invocação orquestrada.

Ferramenta	Descrição
`agent_create`	Criar um agente (opcionalmente a partir de um template) com escopo em um universo / equipe.
`agent_list`	Listar agentes no tenant do chamador. Escopo automático via chave de API.
`agent_get`	Buscar um agente por `agent_id`.
`agent_update`	Atualizar persona, equipe, universo, etc.
`agent_delete`	Excluir um agente.
`agent_invoke`	Invocar programaticamente um agente com uma tarefa. Retorna suas chamadas de ferramenta e a resposta final. Usado por delegação.

Universos (4)

Universo = domínio de conhecimento com escopo de tenant. Contém a hierarquia L0–L3.

Ferramenta	Descrição
`universe_create`	Criar um universo na organização do chamador. Slug + nome + descrição.
`universe_list`	Listar universos para a organização resolvida.
`universe_update`	Atualizar um universo (nome, descrição).
`universe_hierarchy`	Percorrer a árvore completa L0 → L3 para um universo com ícones de status.

Hierarquia de Conhecimento L0–L3 (16)

Universe
  └─ Concept   (L0)  body of knowledge
       └─ Theme  (L1)  thematic split
            └─ Topic   (L2)  unit of work (status: pending / in_progress / completed)
                 └─ Point   (L3)  atomic knowledge unit

Cada nível expõe create, list, update, delete:

Conceitos L0: concept_create, concept_list, concept_update, concept_delete
Temas L1: theme_create, theme_list, theme_update, theme_delete
Tópicos L2: topic_create, topic_list, topic_update, topic_delete
Pontos L3: point_create, point_list, point_update, point_delete

topic_update e point_update aceitam um campo status para que agentes possam marcar progresso.

Pipeline de Treinamento (6)

Ensine o sistema explicitamente — fatos, procedimentos, pares de perguntas e respostas, documentos completos.

Ferramenta	Descrição
`training_teach`	Injetar um fato ou procedimento. `type` ∈ {semântico, procedural}.
`training_qa`	Treinar com `pairs` de `{question, answer}`.
`training_stats`	Estatísticas de cobertura em todo o corpus.
`training_gaps`	Lacunas detectadas no conhecimento / tópicos com cobertura fraca.
`training_recent`	Memórias mais recentemente ingeridas do treinamento.

Orquestração — Tarefas (4)

A tabela de tarefas no Memory Engine conduz a orquestração multiagente.

Ferramenta	Descrição
`task_create`	Criar uma tarefa (título, descrição, `assigned_agent_id` opcional, tarefa pai).
`task_get`	Buscar uma tarefa com seu estado completo.
`task_list`	Listar tarefas com filtros (status, agente, pai).
`task_update`	Atualizar status, saída ou atribuição.

Habilidades (4)

Comportamentos reutilizáveis atribuídos a agentes.

Ferramenta	Descrição
`skill_list`	Enumerar habilidades disponíveis no tenant.
`skill_assign`	Anexar uma habilidade a um agente.
`skill_remove`	Desanexar uma habilidade de um agente.
`skill_agent_list`	Listar as habilidades de um determinado agente.

Cofre de Credenciais (5) — broker `credential_exec`

Credenciais criptografadas armazenadas no Control Plane, referenciadas a partir de memórias via credential_ref.

Ferramenta	Descrição
`credential_store`	Armazenar uma credencial criptografada sob uma referência (ex.: `mysql_x`).
`credential_get`	Inspecionar apenas metadados não secretos (host/usuário/db/porta + as variáveis de ambiente que `credential_exec` injetará). Nunca retorna o valor.
`credential_exec`	Executar um comando com a credencial injetada no ENV do processo filho. Retorna apenas stdout/stderr/exit_code — o segredo nunca chega ao modelo, à tela ou ao disco.
`credential_list`	Listar referências de credenciais armazenadas (sem dados secretos).
`credential_delete`	Excluir uma credencial armazenada.

Princípio de manuseio de segredos — broker no lado do servidor, nunca por valor. O modelo nunca recebe um valor secreto: sem texto simples, sem arquivos temporários, sem trechos de shell que carreguem o segredo. Para usar uma credencial, você chama credential_exec. O servidor MCP (já em execução localmente via npx -y frinus-mcp@latest) busca a credencial no cofre, injeta seus campos no ambiente de um processo filho — nunca em argv, nunca em qualquer texto que o modelo veja — executa o comando com shell:false (sem injeção de shell) e retorna apenas a saída.

// MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected → standard clients just work
credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
credential_exec(ref="pg_prod",    argv=["psql",  "-c", "SELECT 1"])

// For anything else, read the injected vars inside an explicit shell:
credential_exec(ref="jira_x", argv=["sh","-c",
  "curl -sS -H \"Authorization: Bearer $CRED_TOKEN\" \"$CRED_BASE_URL/whoami\""])

Variáveis de ambiente injetadas (quando presentes na credencial): senha/segredo/token → MYSQL_PWD, PGPASSWORD, CRED_PASSWORD; user/username → CRED_USER, MYSQL_USER, PGUSER; host → CRED_HOST, MYSQL_HOST, PGHOST; port → CRED_PORT, MYSQL_TCP_PORT, PGPORT; database → CRED_DATABASE, PGDATABASE; qualquer outro escalar → CRED_<UPPER_SNAKE> (ex.: base_url → CRED_BASE_URL). argv deve ser um array de strings (sem string de comando shell; use ["sh","-c","..."] se você realmente precisar de um shell). Timeout de 30s, limite de saída de 256 KiB. Tudo vem no pacote npm — o usuário não instala nada, não edita o PATH e não executa nenhum comando extra; um MCP atualizado é tudo o que é necessário.

Tipos de Memória

Tipo	Caso de Uso	Exemplo
`episodic`	Registrar o que aconteceu	`Bug: payment endpoint returned 500. Cause: missing null check on customer.address. Fix: guard + 422 response. File: services/payment.py`
`semantic`	Armazenar fatos e conhecimento	`MemoryResponse now includes universe_id (UUID
`procedural`	Documentar procedimentos de como fazer	`Procedure: rotate-claude-credentials. Steps: 1) aws ecr login, 2) kubectl set image deployment/agent..., 3) verify pod is Ready. Caveat: deployment is named "agent", not "agent-service".`

Escopos

Escopo	Visibilidade	Caso de Uso
`user`	Somente o usuário que armazena	Preferências pessoais e histórico
`agent`	Somente o agente que armazena	Notas privadas do agente
`universe`	Todos os agentes dentro do universo (departamento)	Conhecimento de domínio compartilhado
`organization`	Todos os agentes no tenant	Procedimentos e fatos de toda a organização

Os escopos legados agent / project / global foram aposentados juntamente com project_id. Universos substituíram projetos como o limite de isolamento dentro de uma organização.

Melhores Práticas

Formatos obrigatórios para memórias — torne a recuperação futura determinística:

Bug: Bug: <description>. Cause: <root cause>. Fix: <solution>. File: <path>
Padrão: Pattern: <description>. When to use: <context>. File: <path>
Procedimento: Procedure: <name>. Steps: 1) ... 2) ... 3) .... Caveats: <warnings>

Diretrizes operacionais:

Sempre inicialize primeiro. Chame session_start + working_memory_get + search_with_attention antes de responder.
Reforce / enfraqueça no uso. Quando uma memória recuperada ajuda, memory_reinforce. Quando está errada, memory_weaken (e substitua-a).
Capture a cada 2–3 turnos. working_memory_add para estado, stream_capture para decisões, memory_store para aprendizados cristalizados.
Escolha o task_type certo. search_with_attention pondera tipos de memória por tarefa. debug favorece episódica, documentation favorece semântica, deploy favorece procedural.
Feche o ciclo. Termine as sessões com session_summary + stream_process + session_end. Execute sleep_run para consolidação mais profunda quando os lotes crescerem.
Audite antes que a desordem se acumule. consolidation_detect_conflicts + consolidation_detect_redundant periódicos mantêm a recuperação nítida.

Arquitetura

+---------------------+       +------------------+       +----------------------+
| Claude Agent /      | <---> | Frinus MCP       | <---> | Memory Engine        |
| Claude Code         | stdio | (this server)    | HTTPS | (memories, sessions, |
+---------------------+       +------------------+       |  hierarchy, tasks)   |
                                |                        +----------------------+
                                |                                  |
                                |                                  v
                                |                        +----------------------+
                                |                        | PostgreSQL+pgvector  |
                                |                        | + Apache AGE (graph) |
                                |                        +----------------------+
                                |
                                +---HTTPS---> Control Plane (universes, orgs)
                                +---HTTPS---> Agent Service (agents, invocation, skills)

Memory Engine é dono das memórias, memória de trabalho, sessões, streams, hierarquia L0–L3, treinamento, ciclos de sono, tarefas, habilidades.
Control Plane é dono de organizações, universos, membros, chaves de API, cobrança, credenciais, white-label, chaves de LLM.
Agent Service é dono do runtime do agente, despacho de ferramentas, roteamento de equipe, persona, invocação.

O isolamento de tenant é banco-de-dados-por-tenant. O MCP resolve o ID da organização do seu tenant a partir da chave de API na inicialização — você nunca passa org_id manualmente.

Avançado — auto-hospedagem / desenvolvimento local

Tudo acima tem como alvo a plataforma hospedada em https://frinus.rdxsec.com.br,, que é o que quase todo mundo quer. Se você executa sua própria pilha Frinus (ou desenvolve o MCP contra um backend local), compile a partir do código-fonte e substitua as três URLs:

git clone https://github.com/frinus-ai/frinus-mcp && cd frinus-mcp
npm install
npm run build      # emits dist/index.js

{
  "mcpServers": {
    "frinus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-...",
        "MEMORY_SERVICE_URL": "http://localhost:8001",
        "FRINUS_CP_URL": "http://localhost:8000",
        "AGENT_SERVICE_URL": "http://localhost:8002"
      }
    }
  }
}

Publicação (mantenedores)

# 1) npm package — powers `npx -y frinus-mcp` everywhere
npm version <patch|minor|major>
npm publish                      # prepublishOnly runs the build

# 2) .mcpb bundle — powers the Claude Desktop one-click install
npm run pack:mcpb                # -> frinus.mcpb
gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
# Frontend points at: releases/latest/download/frinus.mcpb

Desenvolvimento

mcp/
  src/
    index.ts                       Entry: MCP server, dispatch, auth bootstrap
    client/
      memory-client.ts             HTTP client + identity state for Memory Engine
      cp-client.ts                 HTTP client for Control Plane
      agent-client.ts              HTTP client for Agent Service
    tools/
      definitions.ts               Tool schemas (70 tools)
      handlers.ts                  Tool handlers (70 handlers)
    capture/
      interaction-capture.ts       Auto stream capture for every tool call
    types/
      index.ts                     Shared types
  dist/                            Compiled output (npm run build)
  package.json
  tsconfig.json

Scripts:

npm run build     # tsc to dist/
npm run dev       # tsx hot reload (src/index.ts)
npm start         # node dist/index.js

Verificação de tipos: TypeScript 5.6+, módulos ES, axios.

Licença

Consulte a raiz do repositório para os termos de licença.