Component Registry

What is the Memcity Registry?

The Memcity registry is a shadcn-compatible distribution system for the Memcity Convex backend component. Instead of installing a compiled npm package, you install source code directly into your project's convex/memcity/ directory.

Unlike typical shadcn registries that distribute React UI components, the Memcity registry distributes backend code — the Convex component that powers AI memory, search, and knowledge graph features. You get the full source: schema, queries, mutations, actions, and the Memory client class.

Setup

Step 1: Configure the Registry

Add the Memcity registry to your components.json (create this file at your project root if it doesn't exist):

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@memcity": {
      "url": "https://memcity.dev/r/{name}.json",
      "headers": {
        "X-License-Key": "${MEMCITY_LICENSE_KEY}"
      }
    }
  }
}

How this works: {name} is a shadcn placeholder — it gets automatically replaced with the item name you pass in the install command. For example, npx shadcn@latest add @memcity/pro resolves the URL to https://memcity.dev/r/pro.json. You don't need to change {name} yourself. Similarly, ${MEMCITY_LICENSE_KEY} is read from your .env.local file at install time.

Step 2: Set Your License Key

If you have a Pro or Team license, add your key to .env.local:

# .env.local
MEMCITY_LICENSE_KEY=MEMCITY_PRO_xxxx-xxxx-xxxx-xxxx

The Community tier doesn't need a license key.

Step 3: Install Your Tier

# Community (free) — hybrid vector search, BM25, RRF fusion
npx shadcn@latest add @memcity/community
 
# Pro ($79) — full 16-step RAG pipeline, GraphRAG, file processing, episodic memory
npx shadcn@latest add @memcity/pro
 
# Team ($179) — everything in Pro plus ACLs, audit logging, quotas
npx shadcn@latest add @memcity/team

What Gets Installed

Running the install command creates the following structure in your project:

convex/
├── memory.ts                          ← Pre-configured Memory client (tier pre-set)
└── memcity/
    ├── client.ts                      ← Memory class
    ├── convex.config.ts               ← defineComponent("memory")
    ├── schema.ts                      ← Tables + indexes
    ├── convex.config.snippet.ts       ← Merge guide for your convex.config.ts
    ├── README.md                      ← Setup instructions
    ├── ingest/                        ← Document ingestion pipeline
    ├── search/                        ← Vector search + context retrieval
    ├── graph/                         ← Knowledge graph traversal (Pro/Team)
    ├── memory/                        ← Episodic memory (Pro/Team)
    ├── lib/                           ← Shared utilities (AI, chunking, config)
    ├── jobs/                          ← Background job queue
    └── _generated/                    ← Convex generated files

The exact files included depend on your tier — Community gets a subset, Pro/Team get progressively more.

After Installation

1. Merge the Convex config snippet — Open convex/memcity/convex.config.snippet.ts and merge the app.use(memory) line into your convex/convex.config.ts

2. Set environment variables:

   bashCopy

   npx convex env set JINA_API_KEY your-jina-key
   npx convex env set OPENROUTER_API_KEY your-openrouter-key  # Pro/Team only

3. Use the pre-configured client — Import from convex/memory.ts:

   tsCopy

   import { memory } from "./memory";

Note: shadcn registry cannot reliably auto-patch an existing convex/convex.config.ts. You must merge the snippet manually.

Available Tiers

community (Free)

Hybrid vector search with BM25 keyword matching and Reciprocal Rank Fusion.

npx shadcn@latest add @memcity/community

Includes: Text ingestion, chunking, vector embeddings, semantic search, BM25, RRF fusion, confidence scoring, semantic deduplication.

pro ($79 one-time)

Full 16-step RAG pipeline with advanced search, knowledge graph, and episodic memory.

npx shadcn@latest add @memcity/pro

Adds: Query routing, query decomposition, HyDE, reranking, RAPTOR summaries, knowledge graph, GraphRAG traversal, file processing (25+ types), URL ingestion, episodic memory, cascading deletion.

team ($179 one-time)

Everything in Pro plus enterprise features.

npx shadcn@latest add @memcity/team

Adds: Per-document ACLs, immutable audit logging, usage quotas + rate limiting, multi-organization support.

Authentication Flow

When you run npx shadcn add @memcity/pro, here's what happens:

1. shadcn reads your components.json registry configuration
2. It makes a GET request to https://memcity.dev/r/pro.json
3. Your MEMCITY_LICENSE_KEY is sent in the X-License-Key header
4. The Memcity server validates your key and checks your tier
5. If valid and your tier has access, the full component source is returned as registry JSON
6. shadcn writes the files into convex/memcity/ and installs dependencies

What happens with an invalid key:

Error: 401 Unauthorized
Set MEMCITY_LICENSE_KEY in your .env.local.
Get one at https://memcity.dev/#pricing

What happens with wrong tier:

Error: 403 Forbidden
'team' requires a team license.
Upgrade at https://memcity.dev/#pricing

Direct URL Install

You can install the community tier without configuring the registry:

npx shadcn@latest add https://memcity.dev/r/community.json

This works for community (free) only. Pro/Team require the registry configuration to pass your license key.

Customizing Installed Code

Since you get source code, you can modify anything — schemas, search logic, chunking strategy, AI models:

// convex/memcity/lib/config.ts — change defaults
// convex/memcity/search/context.ts — modify the search pipeline
// convex/memcity/ingest/chunks.ts — adjust chunking strategy

Getting Updates

When Memcity releases a new version, re-install to get the update:

npx shadcn@latest add @memcity/pro

This overwrites the files. If you've made customizations, commit your changes first so you can use git diff to merge.

Troubleshooting