Ratary Memory MCP

---

The problem

Why does AI forget between sessions?

Every AI session starts from zero.

Your model forgets yesterday's architecture decisions. Your agent drops customer context between runs. Your coding assistant can't recall why you chose Postgres over DynamoDB. Teams paste the same background into Cursor, Claude, ChatGPT, and custom bots — and knowledge still drifts.

Vector databases store chunks. RAG pipelines retrieve documents. Agent frameworks orchestrate tools.

None of them give AI a durable brain.

---

Why Ratary exists

Why build a brain layer now?

AI models are getting cheaper. Context windows are getting larger. Agents are getting capable.

But AI still forgets.

The bottleneck is no longer reasoning. It's memory — durable, structured, retrievable, and owned by you.

Every serious application eventually needed a database. Every serious AI system will need a brain layer: persistent intelligence that sits between your models and your storage — independent of any single vendor, IDE, or agent framework.

AI should remember.
Developers should own that memory.

Ratary exists to be that layer. Applications bring models. Ratary brings the brain.

---

What Ratary is

What is Ratary?

Ratary is an AI Brain Platform — infrastructure that gives AI:

• Persistent memory — durable, owner-scoped, versioned
• Structured knowledge — metadata, relations, graph traversal
• Intelligent retrieval — hybrid search + bounded context assembly
• Protocol access — Ratary MCP, REST, optional gRPC

It sits between AI clients and storage. One brain, many surfaces — Cursor, Claude Code, custom agents, enterprise APIs, and remote MCP hosts.

The runnable deployment is Ratary Server — this repository. Ratary is the product; Ratary Server is what you clone and run.

Bring your model. Ratary brings the memory.

---

Quick start

How do I run Ratary Server locally?

Ratary is the product. Ratary Server is the open-source deployment you run — ontorata/ratary (this repository). @ratary/sdk, @ratary/cli, and Ratary MCP connect to it; sibling Ontorata products use the same source of truth.

Prerequisites: Node.js 24 · SQL metadata store (pick one — Postgres is the template default)

Path A — PostgreSQL (npm + local or Docker)

git clone https://github.com/ontorata/ratary.git
cd ratary && npm install
cp .env.example .env   # Set AUTH_SECRET + DATABASE_URL — see .env.example QUICK START
npm run db:apply-postgres-schema
npm run setup          # wire Ratary MCP for Cursor, Claude Code, …
npm run dev

Or use Docker: docker compose --profile postgres up --build — see docs/DOCKER.md.

Path B — Cloudflare D1

git clone https://github.com/ontorata/ratary.git
cd ratary && npm install
cp .env.example .env   # Set AUTH_SECRET + SQL_PROVIDER=d1 + CLOUDFLARE_* / D1_*
npm run db:migrate
npm run setup
npm run dev

Details: docs/GUIDE.md · docs/CONFIGURATION.md

→ API http://localhost:9876 · Swagger /docs

First REST call: bootstrap once to get an API key (aic_...) — see GUIDE — First REST API key.

# Save your first memory
curl -X POST http://localhost:9876/api/v1/memory \
  -H "Authorization: Bearer aic_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello brain","project":"demo","content":"Ratary remembers this."}'

Full guide: docs/GUIDE.md · SDK & MCP examples in docs/examples/

npm packages (@ratary)

Client libraries ship on npm under the @ratary scope — product name, published by Ontorata. No server clone required for SDK, CLI, or hosted MCP.

npm install @ratary/sdk@1.1.0
npx @ratary/mcp-server@1.1.3          # remote REST → stdio MCP
npm install -g @ratary/cli@1.1.0      # operator CLI

Package	Version	Install	Role
@ratary/sdk	1.1.0	npm install @ratary/sdk	Typed REST client + client.admin.*
@ratary/cli	1.1.0	npm install -g @ratary/cli	Operator commands (admin, connectors)
@ratary/mcp-server	1.1.3	npx @ratary/mcp-server	IDE MCP → hosted API

Set RATARY_BASE_URL and RATARY_API_KEY (aic_...). Details: packages/README.md · remote MCP install.

---

Ecosystem

Which repository owns what?

The Visual architecture diagram shows logical layers inside Ratary Server. This diagram shows repository and product relationships — what ships in this repo, what connects to it, and what lives in sibling Ontorata repositories. Both views describe the same platform from different angles.

Throughout this README, Ratary MCP means the official memory MCP implementation (stdio in this repo · npm @ratary/mcp-server for hosted REST). It is not the same as Ontorata MCP (ecosystem gateway — separate repo).

┌─────────────────────────────────────────────────────────────┐
│                      Ratary Cloud (opt-in)                  │
│         optional hosted deployment · not this repo          │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│  Ratary Server          ← ontorata/ratary (this repo)       │
└──────────────────────────────┬──────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
   @ratary/sdk    @ratary/cli   @ratary/mcp-server
   (SDK)          (CLI)         (Ratary MCP · npm)
         │              │              │
         └──────────────┴──────────────┘
                               │
         ┌─────────────────────┴─────────────────────┐
         ▼                     ▼                     ▼
   Ontorata MCP         Ontorata Studio          Ontory Runtime
   ontorata/ontorata-mcp ontorata/Ontorata-Studio  ontorata/ontory-runtime
   ecosystem product     ecosystem product         (ADR-2119; was ontorata/ontory)

Infrastructure (ships from ontorata/ratary — server plus client packages):

Component	Repository	Role
Ratary Server	ontorata/ratary	Memory engine — REST, persistence, Ratary MCP stdio. You run this.
Ratary SDK	npm @ratary/sdk · packages/sdk	Typed REST client for Ratary Server.
Ratary CLI	npm @ratary/cli · packages/cli	Operator commands; delegates to Ratary SDK.
Ratary MCP	npm @ratary/mcp-server · stdio in repo	Memory MCP — full stdio in clone · npm proxy for hosted REST.

Ecosystem products (separate repositories — connect to Ratary Server; not bundled here):

Product	Repository	Role
Ontorata MCP	ontorata/ontorata-mcp	Ecosystem MCP gateway — Ratary MCP plus additional Ontorata tools.
Ontorata Studio	ontorata/Ontorata-Studio	Operator UI — uses @ratary/sdk only.
Ontory	ontorata/ontory-runtime	Ontory Runtime — AI orchestration (ADR-2119). Legacy URL ontorata/ontory redirects.

Ratary Server does not depend on ecosystem product repositories.

Ratary MCP vs Ontorata MCP

Which MCP should I install?

	Ratary MCP	Ontorata MCP
Layer	Ratary infrastructure	Ontorata ecosystem product
What it is	Official memory protocol for Ratary Server	Ecosystem gateway for Ontorata products
Scope	Memory — CRUD, search, context, graph	Ratary memory plus additional Ontorata tools
Repository	ontorata/ratary · npm @ratary/mcp-server	ontorata/ontorata-mcp
Typical mcp.json key	ratary	ontorata

Use Ratary MCP for direct memory access. Use Ontorata MCP for one MCP entry point across the Ontorata stack. Both use Ratary Server as source of truth.

---

What Ratary is not

How is Ratary different from alternatives?

	Vector DB	Memory API	RAG	Agent framework	Ratary
Primary job	Similarity search	Key-value recall	Document Q&A	Tool orchestration	Durable AI memory
Structured knowledge & graph	❌	⚠️	❌	⚠️	✅
MCP-native IDE integration	❌	⚠️	❌	⚠️	✅
Token-efficient context assembly	❌	⚠️	❌	⚠️	✅
Self-host & data sovereignty	✅	⚠️	⚠️	⚠️	✅
Clear agent boundary	N/A	⚠️	N/A	❌ bundled	✅ substrate only

Ratary complements your stack — it does not replace pgvector, LangGraph, or your agent of choice. See the Capability matrix for a feature-level comparison.

If you only use…	You get…	What you miss
pgvector	Embedding similarity	Structured memory, graph, MCP, context packing
Mem0	Fast hosted memory API	Full self-host, hybrid retrieval, enterprise adapters
Letta	Agent + memory bundled	Your agent stays yours — Ratary is substrate, not runtime
LangGraph	Workflow & tool routing	Shared durable memory across sessions and clients
RAG	Document chunks	Evolving memory — decisions, handoffs, relations

---

Visual architecture

How is Ratary Server structured internally?

This diagram shows the logical internal architecture of Ratary — how memory, knowledge, retrieval, and storage layers compose inside the platform. It is not a repository or product map.

        ┌─────────────────────────────────────────┐
        │           Your AI applications           │
        │  Cursor · Claude · Agents · REST · MCP   │
        └────────────────────┬────────────────────┘
                             │
                    MCP · REST · gRPC
                             │
        ┌────────────────────▼────────────────────┐
        │     Ratary Server (logical layers)       │
        │  ┌─────────┐ ┌──────────┐ ┌───────────┐ │
        │  │ Memory  │ │Knowledge │ │ Retrieval │ │
        │  └────┬────┘ └────┬─────┘ └─────┬─────┘ │
        │       └───────────┴─────────────┘       │
        │         Context · Learning · Protocols   │
        └────────────────────┬────────────────────┘
                             │
        ┌────────────────────▼────────────────────┐
        │     Pluggable storage (your choice)      │
        │  Postgres · Supabase · MariaDB · D1 · pgvector · Neo4j · │
        │  R2/S3/MinIO · OpenSearch · ClickHouse · …        │
        └─────────────────────────────────────────┘

Search browses. Retrieval injects context. Embedding enriches asynchronously — never on the CRUD hot path.

Details: docs-ai → products/ratary/roadmap/ARCHITECTURE.md

For repository and product relationships (SDK, CLI, Ratary MCP, Ontorata ecosystem repos), see Ecosystem — a separate diagram, same platform, different perspective.

---

How Ratary works

What happens to a memory after you save it?

   Write          Enrich         Retrieve        Learn          Reuse
     │               │               │              │              │
     ▼               ▼               ▼              ▼              ▼
  Save via       Summarize,      Rank & pack    Signals,       Same memory
  Ratary MCP/REST embed, link     context for    consolidate,   powers every
                 relations       your prompt    evolve         client

1. Write — Persist memory through Ratary MCP or REST.
2. Enrich — Summarize, embed, and relate — asynchronously.
3. Retrieve — Assemble the smallest useful context slice.
4. Learn — Optional signals and consolidation improve recall over time.
5. Reuse — One brain across IDEs, agents, and APIs.

---

Core capabilities

What can Ratary Server do today?

Memory intelligence

Durable memories with summaries, codenames, favorites, archives, and handoffs. Version history with restore and merge — built for long-running work, not chat logs.

Knowledge

Semantic enrichment, relation linking, and graph traversal. Memory becomes navigable knowledge — not a flat pile of notes.

Retrieval

Hybrid search across SQL, vectors, lexical index, and graph. Separate browse from inject. Optional precision modes (hybrid, semantic, fulltext, title) when you need more control.

Reasoning support

Progressive retrieval, token budgets, and summary-first context assembly — typically ~85% fewer tokens than dumping full memory bodies into prompts.

Learning

Quality signals, consolidation, and compression — optional pipelines that improve the brain over time without retraining your model.

External agent support

Capability manifests, workspace scoping, and 28 Ratary MCP tools. External agents discover what the brain can do; Ratary never embeds agent reasoning — see What Ratary is not.

Platform

Pluggable adapters: choose SQL metadata (Postgres, Supabase, MariaDB/MySQL, D1, TiDB/Cockroach) plus optional pgvector, R2/S3/MinIO, Azure Blob, GCS, Meilisearch, OpenSearch, Neo4j, Redis, DuckDB, ClickHouse. Same application code for every backend.

Self-host stacks: docs/DOCKER.md — postgres or enterprise (MariaDB + MinIO + Redis) profiles.

Cloud & enterprise

Self-host, deploy to Vercel, or run a control plane with metering and federation. RBAC workspaces, audit trails, SSO, and policy hooks — opt-in when you need them.

Observability

OpenTelemetry, Prometheus metrics, SLO dashboards, and cost visibility for production brains.

Developer experience

OpenAPI, npm @ratary/sdk@1.1.0 · @ratary/cli@1.1.0 · @ratary/mcp-server@1.1.3 — and one-command IDE setup (npm run setup).

Knowledge fabric (opt-in)

Ingest from external systems of record — Notion (live on hosted prod), Confluence, Google Drive, SharePoint, and Teams connectors (code complete · enable per connector via env). Webhook HMAC, incremental sync, provenance on memories. Flags: KNOWLEDGE_FABRIC_ENABLED + CONNECTOR_SYNC_ENABLED. Guides: Knowledge fabric · Production enable · Phases 32–34 in docs-ai.

---

Use cases

Who is Ratary for?

	What you build	What Ratary provides
Developer AI	Coding assistants across IDEs and sessions	Persistent project memory, MCP tools, handoffs
Enterprise search	Internal knowledge discovery	Hybrid retrieval over structured memory, not just files
Customer support	AI that handles tickets	Durable customer context without re-prompting every thread
Knowledge management	Team second brain	Graph-linked memories, codenames, relations, summaries
Autonomous agents	Multi-agent systems	Shared memory layer with workspace and agent scoping
Personal AI	Private assistant you own	Self-hosted, exportable, sovereign data

---

Capability matrix

How does Ratary compare feature-by-feature?

For category positioning, see What Ratary is not.

Capability	Ratary	Vector DB	Memory API	RAG	Agent framework
Persistent structured memory	✅	❌	⚠️	❌	⚠️
MCP-native	✅	❌	⚠️	❌	⚠️
Hybrid SQL + vector + graph	✅	⚠️	⚠️	⚠️	⚠️
Token-efficient context assembly	✅	❌	⚠️	❌	⚠️
Knowledge graph & relations	✅	❌	⚠️	❌	⚠️
Self-host sovereignty	✅	✅	⚠️	⚠️	⚠️
Agent boundary (bring your agent)	✅	N/A	⚠️	N/A	❌
Enterprise storage adapters	✅	✅	⚠️	⚠️	⚠️

---

Documentation

Where do I read next?

Engineering knowledge (internal)

Architecture, ADRs, roadmap, phases, design history, and reviews live in the Ontorata Knowledge OS:

https://github.com/ontorata/docs-ai → products/ratary/

Operator / developer guides (this repository)

Ratary Server (ontorata/ratary — this repository):

docs/GUIDE.md	Setup, daily usage, Ratary MCP configuration
docs/install/README.md	Per-harness MCP / plugin installation
docs/DOCKER.md	Container & Compose self-host
docs/CONFIGURATION.md	Environment variables — what each flag does
docs/examples/	MCP and IDE config templates
MCP/README.md	Ratary MCP — stdio and @ratary/mcp-server
packages/README.md	npm packages — install, env, publish
.env.example	Env template — meanings in docs/CONFIGURATION.md
docs/PRODUCTION-ENABLE.md	Hosted deploy — knowledge fabric on Vercel
docs/OPS-PRODUCTION-VERIFY.md	Production ops checklist — npm run ops:verify-production
docs/MCP-CHATGPT-OAUTH.md	ChatGPT MCP OAuth + Keycloak IdP runbook
MCP/submission/directory-status.md	MCP directory listing status
docs/ENTERPRISE-MODULES.md	Enterprise flags (opt-in)
CHANGELOG.md	Release notes and version map
SECURITY.md	Vulnerability reporting
ontorata/docs-ai	Architecture · ADR · phases · evidence (Knowledge OS)

Canonical hosted API: https://ratary.ontorata.com (self-host uses your own base URL).

Ontorata ecosystem (separate repositories — not in this tree):

ontorata/ontorata-mcp	Ontorata MCP — ecosystem gateway
ontorata/Ontorata-Studio	Ontorata Studio — operator UI (setup)

---

Roadmap

What is shipping when?

Canonical roadmap / phase history: ontorata/docs-ai → products/ratary/roadmap/ · products/ratary/phases/

Organized by direction — not sprints. Phases 1–31 are implemented in code (gates PASS); platform modules stay opt-in via env unless noted.

	Themes	Code	Ops (prod)	Primary repository
Today (v1.0)	Ratary MCP + REST, hybrid/graph retrieval, peer SQL, Docker, npm @ratary/sdk@1.1.0 · @ratary/mcp-server@1.1.3, remote MCP, Ontorata Studio. Platform (opt-in): knowledge fabric (Notion/Confluence/Drive/SharePoint/Teams live), universal memory fabric (Phase 32), Neptune traversal (Phase 33), federation, global intelligence	✅	Partial	ontorata/ratary
Ops (now)	Prod connector creds · MCP directory follow-ups · ChatGPT OAuth IdP (Keycloak)	✅	⏳	ontorata/ratary

Ops status (2026-07-19): Notion + fabric/federation flags on Vercel ✅ · D1 db:migrate ✅ · SDK codegen CI ✅ (workflow) · Confluence/Drive/SharePoint/Teams creds ⏳ (owner secrets) · Keycloak IdP ⏳ (auth.ontorata.com → deploy Render; prod uses Smithery API-key mode until OAuth enabled) · MCP listings mostly Listed (directory-status.md). Verify: npm run ops:verify-production · OPS-PRODUCTION-VERIFY.md

Enterprise modules ship opt-in via environment flags on Ratary Server — defaults stay lean. See ENTERPRISE-MODULES.md and CONFIGURATION.md.

---

Vision

What is Ratary building toward?

Today every application has a database.

Tomorrow every AI will have a brain.

Ratary is building that layer — open, portable, self-hostable, and protocol-native. Not another chat wrapper. Not another vector dump. Infrastructure for persistent intelligence.

Knowledge should accumulate. Boundaries should be respected. Agents should stay coherent across time.

If you're building AI that lasts longer than a single prompt — build on Ratary.

---

Contributing

How do I contribute?

Ratary Server (this repo): fork ontorata/ratary → branch → npm run lint && npm run build && npm test → PR to ontorata/ratary.

Standard PR gate:

npm run lint && npm run build && npm test

Org-memory / recall changes (maintainers with .ai/ workspace): run the full gate before merge — see docs/RATARY-VALIDATION-RUNBOOK.md:

npm run ci:ratary-validation

Production ops changes (Vercel env, connectors, OAuth): see docs/OPS-PRODUCTION-VERIFY.md:

npm run ops:verify-production

Extended governance (.ai/ phases, ADRs) lives in the development mirror — optional for contributors; docs-only and standard PRs to ontorata/ratary are welcome without the mirror.

Ontorata MCP and Ontorata Studio accept contributions in their own repositories — not via this repo.

Questions: hello@ontorata.com