Ratary

Memória de codificação persistente para assistentes de IA — MCP stdio + URL remota, busca híbrida, grafo de conhecimento, contexto eficiente em tokens. Auto-hospedável no Cloudflare D1 ou Postgres.

GitHub

Experimente este MCPPatrocinado

Documentação

Ratary — Servidor MCP

Categoria: Memória · Transporte: stdio (local) + HTTP Streamable (remoto, opt-in)
Repositório: github.com/ontorata/ratary
Listagem: envie para mcpservers.org com o link https://github.com/ontorata/ratary/tree/main/MCP

Memória de codificação persistente para assistentes de IA — salve, pesquise, construa contexto eficiente em tokens, navegação em grafo de conhecimento e sincronização multi-cliente. Funciona com Cursor, Claude Code, Roo, Cline, Gemini CLI e hosts MCP remotos (URL do aplicativo ChatGPT quando implantado).

Ecossistema: Criado pela Ontorata. Este documento cobre o Ratary Memory MCP (id ratary). Ontorata MCP e Ontorata Studio são repositórios separados.

npm: Proxy REST hospedado — @ratary/mcp-server (org @ratary). O stdio completo (30 ferramentas) exige clonar este repositório.

Onde está o código do servidor?

Modo	Localização	Quando usar
Servidor completo (30 ferramentas)	`src/mcp/stdio.ts` → `src/transport/mcp/mcp-server.ts`	Clone o repositório; qualquer `SQL_PROVIDER` (D1, Postgres, Supabase, MariaDB, …)
Proxy npm (6 ferramentas)	`packages/mcp-server/` (`@ratary/mcp-server`)	Conectar à API REST hospedada com `RATARY_API_KEY`
HTTPS remoto	`src/transport/mcp/remote/`	`REMOTE_MCP_ENABLED=true` em deploy Vercel

Registro SSOT de ferramentas: src/capabilities/mcp-tool-names.ts

Início rápido (stdio local)

Configure um provedor de metadados SQL primeiro — veja CONFIGURAÇÃO — armazenamento de metadados SQL.

1. Pré-requisitos

git clone https://github.com/ontorata/ratary.git
cd ratary
npm install
cp .env.example .env
# Set SQL_PROVIDER + matching credentials (D1, DATABASE_URL, or MARIADB_CONNECTION_STRING)
npm run db:migrate   # D1 only — use db:apply-postgres-schema for Postgres / Supabase

Servidor de desenvolvimento REST: npm run dev → http://localhost:9876 (Swagger /docs). Substitua com PORT em .env.

2. Gerar configuração do MCP

npm run setup

Grava .cursor/mcp.json e .mcp.json automaticamente.

3. Configuração manual (qualquer IDE)

Veja docs/examples/mcp/cursor.mcp.json.example — substitua REPO_PATH pelo caminho do seu clone.

{
  "mcpServers": {
    "ratary": {
      "command": "npx",
      "args": ["-y", "tsx", "REPO_PATH/src/mcp/stdio.ts"],
      "cwd": "REPO_PATH"
    }
  }
}

Recarregue o MCP na sua IDE. Nenhuma chave de API é necessária no Cursor ao usar o modo D1 direto.

API remota / hospedada (pacote npm)

Para equipes que usam um endpoint REST Ratary implantado:

npm install -g @ratary/mcp-server
export RATARY_BASE_URL=https://ratary.ontorata.com
export RATARY_API_KEY=aic_...
ratary-mcp

Exemplo de configuração: docs/examples/mcp/remote-api.mcp.json.example

URL MCP remota (ChatGPT / clientes web)

Implante com:

REMOTE_MCP_ENABLED=true

Endpoint: https://your-host/mcp (Bearer aic_... ou OAuth quando habilitado).
Smoke test de CI: tests/transport/remote-mcp-chatgpt-smoke.test.ts (payload de inicialização estilo ChatGPT).
Detalhes: GUIA — ChatGPT · CONFIGURAÇÃO — Nível 4

Ferramentas (servidor completo — 28)

Ferramenta	Finalidade
`save_memory`, `update_memory`, `delete_memory`	CRUD
`get_memory`, `get_memory_by_codename`, `get_memory_by_path`, `search_memory`	Leitura e busca (modos de precisão quando `PRECISION_SEARCH_ENABLED=true`)
`get_context`, `build_prompt`	Contexto eficiente em tokens (~85% de economia padrão)
`list_projects`, `list_tags`	Navegação
`link_memories`, `list_relations`, `traverse_relations`, `get_graph_capabilities`	Grafo de conhecimento
`list_workspaces`, `list_agents`, `register_agent`	Espaço de trabalho multi-IA
`get_capabilities`, `negotiate_capabilities`	Descoberta de agentes
`submit_signal`	Feedback de qualidade (adaptação de classificação)
`run_stewardship`, `get_compression_status`	Manutenção
`sync_pull`, `sync_push`, `sync_status`	Sincronização multi-cliente (opt-in)
`toggle_favorite`, `archive_memory`	Ciclo de vida

Contrato de erros (`{error, retryable}`)

Falhas de ferramentas nunca aparecem como erros de protocolo MCP. Qualquer exceção de handler — e qualquer argumento inválido/ausente — retorna um resultado de ferramenta estruturado (isError: true) cujo texto é JSON analisável:

{ "error": "<message>", "retryable": false }

retryable é uma dica de comportamento do cliente, não uma declaração sobre a implementação atual:

retryable: true — leituras idempotentes (search_memory, get_memory*, get_context, build_prompt, list_*, traverse_relations, get_capabilities, negotiate_capabilities, get_compression_status, sync_pull, sync_status) falhando transitoriamente. Repita com um backoff curto e limitado (2–3 tentativas).
retryable: false — todas as mutações (save_memory, update_memory, delete_memory, link_memories, toggle_favorite, archive_memory, register_agent, submit_signal, sync_push) além de run_stewardship (uma execução pode ter sucesso parcial entre sub-etapas; repetição automática arrisca manutenção duplicada). Também toda falha determinística (validação, não encontrado, autenticação) em qualquer ferramenta — repetir entrada idêntica não pode ter sucesso.

Orientação ao cliente:

Nunca repita cegamente uma escrita em um timeout ambíguo — um sucesso silencioso seguido de repetição cria duplicatas. Ou passe um request_id (abaixo) para que a repetição seja segura, ou continue o turno e reconcilie no próximo search_memory/recuperação.
Trate a memória como contexto de melhor esforço, não uma dependência rígida. Se uma chamada falhar, prossiga com o contexto que você já tem e tente novamente no próximo turno. Uma escrita perdida é recuperável; um turno de agente travado não é.
Fonte de verdade da classificação: src/transport/mcp/mcp-tool-retry-classification.ts · suíte de regressão do contrato: tests/mcp-error-contract/.

Criações idempotentes (`request_id`)

save_memory aceita um request_id opcional (UUID, mesmo estilo do submit_signal's signal_id). Gere um por criação lógica e reutilize-o em cada repetição dessa criação:

A primeira chamada com um request_id dado cria a memória normalmente.
Qualquer repetição com o mesmo request_id — incluindo após um timeout ambíguo — retorna a memória original como sucesso, enriquecida com "duplicate": true, "replayed": true. Nenhuma segunda linha é jamais criada, mesmo que a primeira tentativa tenha falhado no meio da escrita.
Itens de criação sync_push recebem a mesma proteção automaticamente, chaveada pelo memory_id do item — reenviar um lote reproduz em vez de duplicar.

A idempotência é garantida enquanto o registro de intenção existir. Registros de intenção concluídos são podados após WRITE_INTENT_TTL_DAYS (padrão de 30 dias) como política de limpeza — uma repetição que chegar após essa janela pode criar uma duplicata. A limpeza nunca exclui uma intenção não resolvida (reivindicada sem resultado); essas são mantidas e apresentadas nas conclusões de administração. Sem um request_id, o comportamento permanece inalterado: salvamentos idênticos criam memórias distintas.

Design: ADR-067 · suíte de contrato: tests/idempotent-writes/.

Listagens de diretórios (Fase 31L)

Envie o Ratary Memory MCP para diretórios públicos usando o pacote de copiar-e-colar em MCP/submission/.

Arquivo do pacote	Diretório
submission/mcpservers-org.md	mcpservers.org/submit — categoria Memória
submission/official-registry.server.json	Official MCP Registry
submission/awesome-mcp-servers-entry.md	PRs do awesome-mcp-servers no GitHub
submission/cursor-marketplace.md	Marketplace de plugins do Cursor
submission/claude-marketplace.md	Marketplace de plugins do Claude Code
submission/directory-status.md	Rastreamento do operador (Pronto → Enviado → Listado)

mcpservers.org (cópia rápida)

Campo	Valor
Nome do servidor	Ratary
Descrição curta	Memória de codificação persistente para assistentes de IA — salve, pesquise, recuperação híbrida, grafo de conhecimento, contexto eficiente em tokens. MCP stdio (30 ferramentas), proxy npm ou HTTP Streamable remoto. Self-hosting em D1, Postgres, Supabase, MariaDB ou Docker.
Link	`https://github.com/ontorata/ratary/tree/main/MCP`
Categoria	Memória
Contato	hello@ontorata.com

Manifestos de marketplace harness

Caminho	Propósito
harness/marketplace/ratary-marketplace.json	Fonte do Claude Code `/plugin marketplace add`
harness/claude-code/plugin.json	Stub de metadados do plugin
harness/marketplace/README.md	Instruções de publicação

SSOT de metadados

Metadados locais do repositório para ferramentas: server.json (flags stdio + npm + remote). A publicação no registro usa submission/official-registry.server.json.

Limite: Liste apenas Ratary Memory MCP (ratary) — não Ontorata MCP nem Ontorata Studio.

Documentação

Documento	Propósito
docs/install/README.md	Instalação por harness (Cursor, Claude, remoto, …)
MCP/submission/README.md	Listagem de diretório do pacote de submissão (31L)
docs/GUIDE.md	Configuração e uso
docs/DOCKER.md	Self-host em contêiner
docs/README.md	Índice de documentação humana
docs/examples/	Configurações MCP, templates de IDE, padrões de SDK

Licença

MIT — consulte LICENSE na raiz do repositório.

Ratary

Documentação

Ratary — Servidor MCP

Onde está o código do servidor?

Início rápido (stdio local)

1. Pré-requisitos

2. Gerar configuração do MCP

3. Configuração manual (qualquer IDE)

API remota / hospedada (pacote npm)

URL MCP remota (ChatGPT / clientes web)

Ferramentas (servidor completo — 28)

Contrato de erros ({error, retryable})

Criações idempotentes (request_id)

Listagens de diretórios (Fase 31L)

mcpservers.org (cópia rápida)

Manifestos de marketplace harness

SSOT de metadados

Documentação

Licença

Contrato de erros (`{error, retryable}`)

Criações idempotentes (`request_id`)