Ratary

Memoria de codificación persistente para asistentes de IA — MCP stdio + URL remota, búsqueda híbrida, grafo de conocimiento, contexto eficiente en tokens. Autoalojamiento en Cloudflare D1 o Postgres.

GitHub

Prueba este MCPPatrocinado

Documentación

Ratary — Servidor MCP

Categoría: Memoria · Transporte: stdio (local) + HTTP Streamable (remoto, opcional)
Repositorio: github.com/ontorata/ratary
Listado: enviar a mcpservers.org con enlace https://github.com/ontorata/ratary/tree/main/MCP

Memoria de codificación persistente para asistentes de IA: guarda, busca, construye contexto eficiente en tokens, recorrido de grafo de conocimiento y sincronización multi-cliente. Funciona con Cursor, Claude Code, Roo, Cline, Gemini CLI y hosts MCP remotos (URL de la app de ChatGPT cuando está desplegado).

Ecosistema: Construido por Ontorata. Este documento cubre Ratary Memory MCP (id ratary). Ontorata MCP y Ontorata Studio son repositorios separados.

npm: Proxy REST alojado — @ratary/mcp-server (organización @ratary). El stdio completo (30 herramientas) requiere clonar este repositorio.

¿Dónde está el código del servidor?

Modo	Ubicación	Cuándo usar
Servidor completo (30 herramientas)	`src/mcp/stdio.ts` → `src/transport/mcp/mcp-server.ts`	Clonar repositorio; cualquier `SQL_PROVIDER` (D1, Postgres, Supabase, MariaDB, …)
Proxy npm (6 herramientas)	`packages/mcp-server/` (`@ratary/mcp-server`)	Conectar a la API REST alojada con `RATARY_API_KEY`
HTTPS remoto	`src/transport/mcp/remote/`	`REMOTE_MCP_ENABLED=true` en despliegue de Vercel

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

Inicio rápido (stdio local)

Configura un proveedor de metadatos SQL primero — consulta CONFIGURACIÓN — Almacén de metadatos SQL.

1. Requisitos previos

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 desarrollo REST: npm run dev → http://localhost:9876 (Swagger /docs). Sobrescribe con PORT en .env.

2. Generar configuración de MCP

npm run setup

Escribe .cursor/mcp.json y .mcp.json automáticamente.

3. Configuración manual (cualquier IDE)

Consulta docs/examples/mcp/cursor.mcp.json.example — reemplaza REPO_PATH con la ruta de tu clon.

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

Recarga MCP en tu IDE. No se necesita clave API en Cursor cuando se usa el modo D1 directo.

API remota / alojada (paquete npm)

Para equipos que usan un endpoint REST de Ratary desplegado:

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

Ejemplo de configuración: docs/examples/mcp/remote-api.mcp.json.example

URL MCP remota (ChatGPT / clientes web)

Despliega con:

REMOTE_MCP_ENABLED=true

Endpoint: https://your-host/mcp (Bearer aic_... u OAuth cuando esté habilitado).
Prueba de humo CI: tests/transport/remote-mcp-chatgpt-smoke.test.ts (payload de inicialización estilo ChatGPT).
Detalles: GUÍA — ChatGPT · CONFIGURACIÓN — Nivel 4

Herramientas (servidor completo — 28)

Herramienta	Propósito
`save_memory`, `update_memory`, `delete_memory`	CRUD
`get_memory`, `get_memory_by_codename`, `get_memory_by_path`, `search_memory`	Lectura y búsqueda (modos de precisión cuando `PRECISION_SEARCH_ENABLED=true`)
`get_context`, `build_prompt`	Contexto eficiente en tokens (~85% de ahorro por defecto)
`list_projects`, `list_tags`	Navegación
`link_memories`, `list_relations`, `traverse_relations`, `get_graph_capabilities`	Grafo de conocimiento
`list_workspaces`, `list_agents`, `register_agent`	Espacio de trabajo multi-IA
`get_capabilities`, `negotiate_capabilities`	Descubrimiento de agentes
`submit_signal`	Retroalimentación de calidad (adaptación de ranking)
`run_stewardship`, `get_compression_status`	Mantenimiento
`sync_pull`, `sync_push`, `sync_status`	Sincronización multi-cliente (opt-in)
`toggle_favorite`, `archive_memory`	Ciclo de vida

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

Los fallos de herramientas nunca se presentan como errores de protocolo MCP. Cualquier excepción de manejador — y cualquier argumento inválido o faltante — devuelve un resultado de herramienta estructurado (isError: true) cuyo texto es JSON analizable:

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

retryable es una pista de comportamiento del cliente, no una declaración sobre la implementación actual:

retryable: true — lecturas idempotentes (search_memory, get_memory*, get_context, build_prompt, list_*, traverse_relations, get_capabilities, negotiate_capabilities, get_compression_status, sync_pull, sync_status) que fallan transitoriamente. Reintenta con un retroceso corto y acotado (2–3 intentos).
retryable: false — todas las mutaciones (save_memory, update_memory, delete_memory, link_memories, toggle_favorite, archive_memory, register_agent, submit_signal, sync_push) más run_stewardship (una ejecución puede tener éxito parcial entre sub-etapas; el reintento automático arriesga mantenimiento doble). También cada fallo determinista (validación, no encontrado, autenticación) en cualquier herramienta — reintentar una entrada idéntica no puede tener éxito.

Orientación para el cliente:

Nunca reintentes a ciegas una escritura en un tiempo de espera ambiguo — un éxito silencioso seguido de un reintento crea duplicados. O pasa un request_id (abajo) para que el reintento sea seguro, o continúa el turno y concilia en el próximo search_memory/recuperación.
Trata la memoria como contexto de mejor esfuerzo, no como una dependencia dura. Si una llamada falla, continúa con el contexto que ya tienes e inténtalo de nuevo en el próximo turno. Una escritura perdida es recuperable; un turno de agente bloqueado no lo es.
Fuente de verdad de clasificación: src/transport/mcp/mcp-tool-retry-classification.ts · suite de regresión de contrato: tests/mcp-error-contract/.

Creaciones idempotentes (`request_id`)

save_memory acepta un request_id opcional (UUID, mismo estilo que el signal_id de submit_signal). Genera uno por creación lógica y reutilízalo en cada reintento de esa creación:

La primera llamada con un request_id dado crea la memoria normalmente.
Cualquier reintento con el mismo request_id — incluso después de un tiempo de espera ambiguo — devuelve la memoria original como éxito, enriquecida con "duplicate": true, "replayed": true. Nunca se crea una segunda fila, incluso si el primer intento falló a mitad de escritura.
Los elementos de creación de sync_push reciben la misma protección automáticamente, clave por el memory_id del elemento — reenviar un lote reproduce en lugar de duplicar.

La idempotencia está garantizada mientras exista el registro de intención. Los registros de intención completados se podan después de WRITE_INTENT_TTL_DAYS (30 días por defecto) como política de limpieza — un reintento que llegue después de esa ventana puede crear un duplicado. La limpieza nunca elimina una intención no resuelta (reclamada sin resultado); esas se conservan y se muestran en los hallazgos de administración. Sin un request_id, el comportamiento no cambia: guardados idénticos crean memorias distintas.

Diseño: ADR-067 · suite de contrato: tests/idempotent-writes/.

Listados de directorios (Fase 31L)

Envía Ratary Memory MCP a directorios públicos usando el paquete de copiar y pegar en MCP/submission/.

Archivo del paquete	Directorio
submission/mcpservers-org.md	mcpservers.org/submit — categoría Memoria
submission/official-registry.server.json	Registro Oficial de MCP
submission/awesome-mcp-servers-entry.md	PRs de GitHub de awesome-mcp-servers
submission/cursor-marketplace.md	Mercado de plugins de Cursor
submission/claude-marketplace.md	Mercado de plugins de Claude Code
submission/directory-status.md	Seguimiento del operador (Listo → Enviado → Listado)

mcpservers.org (copia rápida)

Campo	Valor
Nombre del servidor	Ratary
Descripción corta	Memoria de codificación persistente para asistentes de IA — guarda, busca, recuperación híbrida, grafo de conocimiento, contexto eficiente en tokens. MCP stdio (30 herramientas), proxy npm o HTTP Streamable remoto. Autoalojado en D1, Postgres, Supabase, MariaDB o Docker.
Enlace	`https://github.com/ontorata/ratary/tree/main/MCP`
Categoría	Memoria
Contacto	hello@ontorata.com

Manifiestos de mercado de arneses

Ruta	Propósito
harness/marketplace/ratary-marketplace.json	Fuente de Claude Code `/plugin marketplace add`
harness/claude-code/plugin.json	Stub de metadatos del plugin
harness/marketplace/README.md	Instrucciones de publicación

Metadatos SSOT

Metadatos locales del repositorio para herramientas: server.json (stdio + npm + banderas remotas). La publicación en el registro usa submission/official-registry.server.json.

Límite: Lista solo Ratary Memory MCP (ratary) — no Ontorata MCP ni Ontorata Studio.

Documentación

Documento	Propósito
docs/install/README.md	Instalación por harness (Cursor, Claude, remoto, …)
MCP/submission/README.md	Listado de directorio del paquete de envío (31L)
docs/GUIDE.md	Configuración y uso
docs/DOCKER.md	Autoalojamiento en contenedor
docs/README.md	Índice de documentación humana
docs/examples/	Configuraciones MCP, plantillas IDE, patrones SDK

Licencia

MIT — ver LICENSE en la raíz del repositorio.

Ratary

Documentación

Ratary — Servidor MCP

¿Dónde está el código del servidor?

Inicio rápido (stdio local)

1. Requisitos previos

2. Generar configuración de MCP

3. Configuración manual (cualquier IDE)

API remota / alojada (paquete npm)

URL MCP remota (ChatGPT / clientes web)

Herramientas (servidor completo — 28)

Contrato de errores ({error, retryable})

Creaciones idempotentes (request_id)

Listados de directorios (Fase 31L)

mcpservers.org (copia rápida)

Manifiestos de mercado de arneses

Metadatos SSOT

Documentación

Licencia

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

Creaciones idempotentes (`request_id`)