Component Registry

What is the Memcity Registry?

The Memcity registry is a shadcn-compatible component distribution system. Instead of installing a compiled npm package, you install source code directly into your project.

Think of it like copying a well-built component from a recipe book into your kitchen — it's yours to modify however you want.

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}"
      }
    }
  }
}

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

Community components don't need a license key.

Step 3: Install a Component

npx shadcn@latest add @memcity/memory-search

This downloads source files into your project, installs dependencies, and scaffolds Convex files under convex/memcity/.

Memcity registry installs now also scaffold Convex files:

• convex/memcity/* for installed blocks
• convex/memory.ts with a default Memory client
• convex/memcity/convex.config.snippet.ts with the app.use(memcity) snippet

Note: shadcn registry does not reliably auto-patch an existing convex/convex.config.ts. Merge the snippet into your current file.

Available Components

memory-search (Community — Free)

A drop-in search interface with a search input, results list, and relevance scoring.

npx shadcn@latest add @memcity/memory-search

What you get:

• MemorySearch — Full search UI component
• SearchInput — Styled search input with keyboard shortcuts
• SearchResults — Results list with relevance scores and snippets
• useMemorySearch — React hook for search state management

Usage:

import { MemorySearch } from "@/convex/memcity/memory-search";
 
function DocsPage() {
  return (
    <MemorySearch
      knowledgeBaseId="kb_xyz"
      placeholder="Search documentation..."
      maxResults={10}
    />
  );
}

rag-pipeline (Pro — $79)

A visualization of the full 16-step RAG pipeline with real-time step indicators.

npx shadcn@latest add @memcity/rag-pipeline

What you get:

• RagPipeline — Pipeline visualization component
• PipelineStep — Individual step indicator with timing
• PipelineResults — Results display with confidence bars
• Step-by-step animation showing which parts of the pipeline are active

knowledge-graph (Pro — $79)

An interactive graph viewer showing entities and relationships.

npx shadcn@latest add @memcity/knowledge-graph

What you get:

• KnowledgeGraph — Interactive force-directed graph visualization
• EntityCard — Entity detail popup
• RelationshipLine — Styled relationship connectors
• Pan, zoom, and click-to-explore interactions

file-uploader (Pro — $79)

Drag-and-drop multi-file upload with processing progress.

npx shadcn@latest add @memcity/file-uploader

What you get:

• FileUploader — Drag-and-drop upload zone
• FileProgress — Per-file processing progress bar
• FileList — List of uploaded/processed files
• Automatic file type detection and validation

admin-dashboard (Team — $179)

A complete admin panel for managing ACLs, viewing audit logs, and monitoring quotas.

npx shadcn@latest add @memcity/admin-dashboard

What you get:

• AclManager — Set and view document permissions
• AuditLogViewer — Filterable audit log table
• QuotaMonitor — Usage bars and quota management
• OrgSwitcher — Multi-organization navigation

Authentication Flow

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

1. shadcn reads your components.json registry configuration
2. It makes a GET request to https://memcity.dev/r/rag-pipeline.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 component JSON is returned
6. shadcn installs the files into your project

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
'rag-pipeline' requires a Pro license.
Upgrade at https://memcity.dev/#pricing

Direct URL Install

You can install community components without configuring the registry:

npx shadcn@latest add https://memcity.dev/r/memory-search.json

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

Customizing Installed Components

Since you get source code, you can modify anything:

Styling

Components use Tailwind CSS classes. Change colors, spacing, borders — whatever you want:

// Before (Memcity default)
<div className="border-2 border-dashed border-[#1a1a1a]/20">
 
// After (your brand)
<div className="border rounded-lg border-blue-200 shadow-sm">

Behavior

Add features, remove features, change the search flow:

// Add a "Copy" button to each result
function SearchResult({ result }) {
  return (
    <div>
      <p>{result.text}</p>
      <button onClick={() => navigator.clipboard.writeText(result.text)}>
        Copy
      </button>
    </div>
  );
}

Getting Updates

When Memcity releases a new version of a component, you can re-install to get the update:

npx shadcn@latest add @memcity/memory-search

This overwrites the files. If you've made customizations, you'll need to merge them manually. We recommend committing your changes before re-installing so you can use git diff to merge.

Troubleshooting