Getting Started

{
  "registries": {
    "@memcity": {
      "url": "https://memcity.dev/r/{name}.json",
      "headers": {
        "X-License-Key": "${MEMCITY_LICENSE_KEY}"
      }
    }
  }
}

# Community (free) — basic vector search
npx shadcn@latest add @memcity/memory-search
 
# Pro ($79) — full 16-step RAG pipeline
npx shadcn@latest add @memcity/rag-pipeline
 
# Pro — multi-file upload with processing
npx shadcn@latest add @memcity/file-uploader

# Community (free) — no license key needed
curl -O https://memcity.dev/download?tier=community
 
# Pro/Team — requires your license key
curl -O "https://memcity.dev/download?key=MEMCITY_PRO_xxxx-xxxx-xxxx"

unzip memcity-community.zip -d packages/memcity

// convex/convex.config.ts
import { defineApp } from "convex/server";
import memcity from "memcity/convex.config.js";
 
const app = defineApp();
 
// This line installs Memcity's tables, indexes, and functions
// into your Convex deployment. It runs alongside your own code.
app.use(memcity);
 
export default app;

# Required for ALL tiers — powers embeddings and reranking
# Jina v4 turns your text into 1024-dimensional vectors for search
# Jina Reranker v3 re-scores results for higher precision
npx convex env set JINA_API_KEY your-jina-api-key-here
 
# Required for Pro and Team tiers — powers LLM reasoning
# Used for query routing, entity extraction, HyDE generation,
# and other AI features that need language understanding
npx convex env set OPENROUTER_API_KEY your-openrouter-key-here

// convex/myFunctions.ts
import { Memory } from "memcity";
import { components } from "./_generated/api";
 
// Create a Memory instance with your desired configuration
const memory = new Memory(components.memcity, {
  // Which tier you're on — controls which features are available
  tier: "pro", // "community" | "pro" | "team"
 
  // AI model configuration
  ai: {
    // "openrouter" routes through OpenRouter (recommended)
    // "vercel" routes through Vercel AI Gateway
    gateway: "openrouter",
 
    // The model used for reasoning tasks
    // (query routing, entity extraction, etc.)
    // This is NOT the embedding model — embeddings always use Jina v4
    model: "google/gemini-2.0-flash-001",
  },
 
  // Search behavior — sensible defaults, tune later
  search: {
    maxResults: 10,        // How many results to return
    minScore: 0.1,         // Minimum relevance score (0-1)
    weights: {
      semantic: 0.7,       // Weight for meaning-based search
      bm25: 0.3,           // Weight for keyword-based search
    },
  },
});

// convex/example.ts
import { action } from "./_generated/server";
import { v } from "convex/values";
import { Memory } from "memcity";
import { components } from "./_generated/api";
 
const memory = new Memory(components.memcity, {
  tier: "pro",
  ai: {
    gateway: "openrouter",
    model: "google/gemini-2.0-flash-001",
  },
});
 
// Ingest a document into a knowledge base
export const ingestDocument = action({
  args: {},
  handler: async (ctx) => {
    // Create an organization (top-level container)
    const orgId = await memory.createOrg(ctx, {
      name: "My Company",
    });
 
    // Create a knowledge base (a collection of related documents)
    const kbId = await memory.createKnowledgeBase(ctx, {
      orgId,
      name: "Company Policies",
      description: "HR policies, handbooks, and procedures",
    });
 
    // Ingest a document — Memcity will automatically:
    // 1. Split it into chunks (~512 tokens each)
    // 2. Generate vector embeddings for each chunk
    // 3. Index chunks for semantic and keyword search
    // 4. Extract entities and relationships for the knowledge graph
    await memory.ingestText(ctx, {
      orgId,
      knowledgeBaseId: kbId,
      text: `
        # Vacation Policy
 
        All full-time employees are entitled to 20 days of paid
        vacation per year. Vacation days do not roll over.
 
        ## Requesting Time Off
 
        Submit vacation requests at least 2 weeks in advance
        through the HR portal. Your manager must approve the
        request within 3 business days.
 
        ## Sick Leave
 
        Sick leave is separate from vacation. You get 10 sick
        days per year. A doctor's note is required for absences
        longer than 3 consecutive days.
      `,
      source: "vacation-policy.md",
    });
 
    return { orgId, kbId };
  },
});
 
// Search the knowledge base
export const searchDocs = action({
  args: {
    query: v.string(),
    orgId: v.string(),
    knowledgeBaseId: v.string(),
  },
  handler: async (ctx, args) => {
    const results = await memory.getContext(ctx, {
      orgId: args.orgId,
      knowledgeBaseId: args.knowledgeBaseId,
      query: args.query,
    });
 
    // results.results is an array of matching chunks:
    // - text: the matching text content
    // - score: relevance score (0-1)
    // - confidence: how confident Memcity is in this result
    // - citations: page/line/heading breadcrumbs
    // - source: which document this came from
    return results;
  },
});

// In your React component
const { orgId, kbId } = await ingestDocument();
 
// Ask a natural language question
const results = await searchDocs({
  query: "How many vacation days do I get?",
  orgId,
  knowledgeBaseId: kbId,
});
 
// results.results[0].text →
//   "All full-time employees are entitled to 20 days..."
// results.results[0].score → 0.92
// results.results[0].confidence → 0.87