Ratary

Ratary — MCP Server

Category: Memory · Transport: stdio (local) + Streamable HTTP (remote, opt-in)
Repository: github.com/ontorata/ratary
Listing: submit to mcpservers.org with link https://github.com/ontorata/ratary/tree/main/MCP

Persistent coding memory for AI assistants — save, search, build token-efficient context, knowledge graph traversal, and multi-client sync. Works with Cursor, Claude Code, Roo, Cline, Gemini CLI, and remote MCP hosts (ChatGPT App URL when deployed).

Ecosystem: Built by Ontorata. This doc covers Ratary Memory MCP (id ratary). Ontorata MCP and Ontorata Studio are separate repos.

npm: Hosted REST proxy — @ratary/mcp-server (@ratary org). Full stdio (28 tools) requires cloning this repo.

---

Where is the server code?

Mode	Location	When to use
Full server (28 tools)	src/mcp/stdio.ts → src/transport/mcp/mcp-server.ts	Clone repo; any SQL_PROVIDER (D1, Postgres, Supabase, MariaDB, …)
npm proxy (6 tools)	packages/mcp-server/ (@ratary/mcp-server)	Connect to hosted REST API with RATARY_API_KEY
Remote HTTPS	src/transport/mcp/remote/	REMOTE_MCP_ENABLED=true on Vercel deploy

Tool registry SSOT: src/capabilities/mcp-tool-names.ts

---

Quick start (local stdio)

Configure one SQL metadata provider first — see CONFIGURATION — SQL metadata store.

1. Prerequisites

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

REST dev server: npm run dev → http://localhost:9876 (Swagger /docs). Override with PORT in .env.

2. Generate MCP config

npm run setup

Writes .cursor/mcp.json and .mcp.json automatically.

3. Manual config (any IDE)

See docs/examples/mcp/cursor.mcp.json.example — replace REPO_PATH with your clone path.

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

Reload MCP in your IDE. No API key needed in Cursor when using direct D1 mode.

---

Remote / hosted API (npm package)

For teams using a deployed Ratary REST endpoint:

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

Config example: docs/examples/mcp/remote-api.mcp.json.example

---

Remote MCP URL (ChatGPT / web clients)

Deploy with:

REMOTE_MCP_ENABLED=true

Endpoint: https://your-host/mcp (Bearer aic_... or OAuth when enabled).
CI smoke: tests/transport/remote-mcp-chatgpt-smoke.test.ts (ChatGPT-style initialize payload).
Details: GUIDE — ChatGPT · CONFIGURATION — Tier 4

---

Tools (full server — 28)

Tool	Purpose
save_memory, update_memory, delete_memory	CRUD
get_memory, get_memory_by_codename, get_memory_by_path, search_memory	Read & search (precision modes when PRECISION_SEARCH_ENABLED=true)
get_context, build_prompt	Token-efficient context (~85% savings default)
list_projects, list_tags	Navigation
link_memories, list_relations, traverse_relations, get_graph_capabilities	Knowledge graph
list_workspaces, list_agents, register_agent	Multi-AI workspace
get_capabilities, negotiate_capabilities	Agent discovery
submit_signal	Quality feedback (ranking adaptation)
run_stewardship, get_compression_status	Maintenance
sync_pull, sync_push, sync_status	Multi-client sync (opt-in)
toggle_favorite, archive_memory	Lifecycle

---

Error contract ({error, retryable})

Tool failures never surface as MCP protocol errors. Any handler exception — and any invalid/missing argument — returns a structured tool result (isError: true) whose text is parseable JSON:

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

retryable is a client-behavior hint, not a statement about the current implementation:

• retryable: true — idempotent reads (search_memory, get_memory*, get_context, build_prompt, list_*, traverse_relations, get_capabilities, negotiate_capabilities, get_compression_status, sync_pull, sync_status) failing transiently. Retry with a short bounded backoff (2–3 attempts).
• retryable: false — all mutations (save_memory, update_memory, delete_memory, link_memories, toggle_favorite, archive_memory, register_agent, submit_signal, sync_push) plus run_stewardship (one run may partially succeed across sub-stages; automatic retry risks double maintenance). Also every deterministic failure (validation, not-found, auth) on any tool — retrying identical input cannot succeed.

Client guidance:

1. Never blind-retry a write on an ambiguous timeout — a silent success followed by a retry creates duplicates. Either pass a request_id (below) so the retry is safe, or continue the turn and reconcile on the next search_memory/recall.
2. Treat memory as best-effort context, not a hard dependency. If a call fails, proceed with the context you already have and try again next turn. A missed write is recoverable; a crashed agent turn is not.
3. Classification source of truth: src/transport/mcp/mcp-tool-retry-classification.ts · contract regression suite: tests/mcp-error-contract/.

Idempotent creates (request_id)

save_memory accepts an optional request_id (UUID, same style as submit_signal's signal_id). Generate one per logical create and reuse it on every retry of that create:

• First call with a given request_id creates the memory normally.
• Any retry with the same request_id — including after an ambiguous timeout — returns the original memory as a success, enriched with "duplicate": true, "replayed": true. No second row is ever created, even if the first attempt crashed mid-write.
• sync_push create items get the same protection automatically, keyed by the item's memory_id — re-pushing a batch replays instead of duplicating.

Idempotency is guaranteed while the intent record exists. Completed intent records are pruned after WRITE_INTENT_TTL_DAYS (default 30 days) as a cleanup policy — a retry arriving after that window may create a duplicate. Cleanup never deletes an unresolved (claimed-without-result) intent; those are kept and surfaced in stewardship findings. Without a request_id, behavior is unchanged: identical saves create distinct memories.

Design: ADR-067 · contract suite: tests/idempotent-writes/.

---

Directory listings (Phase 31L)

Submit Ratary Memory MCP to public directories using the copy-paste pack in MCP/submission/.

Pack file	Directory
submission/mcpservers-org.md	mcpservers.org/submit — Memory category
submission/official-registry.server.json	Official MCP Registry
submission/awesome-mcp-servers-entry.md	awesome-mcp-servers GitHub PRs
submission/cursor-marketplace.md	Cursor plugin marketplace
submission/claude-marketplace.md	Claude Code plugin marketplace
submission/directory-status.md	Operator tracking (Ready → Submitted → Listed)

mcpservers.org (quick copy)

Field	Value
Server name	Ratary
Short description	Persistent coding memory for AI assistants — save, search, hybrid retrieval, knowledge graph, token-efficient context. MCP stdio (28 tools), npm proxy, or remote Streamable HTTP. Self-host on D1, Postgres, Supabase, MariaDB, or Docker.
Link	https://github.com/ontorata/ratary/tree/main/MCP
Category	Memory
Contact	hello@ontorata.com

Harness marketplace manifests

Path	Purpose
harness/marketplace/ratary-marketplace.json	Claude Code /plugin marketplace add source
harness/claude-code/plugin.json	Plugin metadata stub
harness/marketplace/README.md	Publish instructions

Metadata SSOT

Repo-local metadata for tooling: server.json (stdio + npm + remote flags). Registry publish uses submission/official-registry.server.json.

Boundary: List Ratary Memory MCP (ratary) only — not Ontorata MCP or Ontorata Studio.

---

Docs

Doc	Purpose
docs/install/README.md	Per-harness installation (Cursor, Claude, remote, …)
MCP/submission/README.md	Directory listing submission pack (31L)
docs/GUIDE.md	Setup & usage
docs/DOCKER.md	Container self-host
docs/README.md	Human docs index
docs/examples/	MCP configs, IDE templates, SDK patterns

License

MIT — see LICENSE in repository root.