API Reference

import { Memory } from "memcity";
import { components } from "./_generated/api";
 
const memory = new Memory(components.memcity, config);

const orgId = await memory.createOrg(ctx, {
  name: "Acme Corp",
});

const kbId = await memory.createKnowledgeBase(ctx, {
  orgId: "org_abc123",
  name: "Product Documentation",
  description: "All product docs, guides, and tutorials",
});

await memory.ingestText(ctx, {
  orgId: "org_abc123",
  knowledgeBaseId: "kb_xyz",
  text: "Your document content here...",
  source: "document.md",
});

const results = await memory.getContext(ctx, {
  orgId: "org_abc123",
  knowledgeBaseId: "kb_xyz",
  query: "How does authentication work?",
});

interface ContextResult {
  results: Array<{
    text: string;           // The matching text content
    score: number;          // Relevance score (0-1)
    confidence: number;     // Confidence level (0-1)
    source: string;         // Source document identifier
    documentId: string;     // Convex document ID
    chunkId: string;        // Specific chunk ID
    citations: {
      source: string;       // File name
      heading: string;      // Section heading breadcrumb
      page: number;         // Page number (if applicable)
      lineStart: number;    // Starting line
      lineEnd: number;      // Ending line
    } | null;
  }>;
  queryType: "simple" | "moderate" | "complex";
  fromCache: boolean;       // Whether embedding was cached
  timings: {
    total: number;          // Total pipeline time (ms)
    embedding: number;      // Embedding generation time
    search: number;         // Vector + BM25 search time
    reranking: number;      // Reranker time
    graph: number;          // GraphRAG traversal time
  };
}

const results = await memory.getContext(ctx, {
  orgId: "org_abc123",
  knowledgeBaseId: "kb_xyz",
  query: "What are the deployment requirements?",
  userId: "user_456",            // Include episodic memories
  conversationId: "conv_789",   // Include conversation context
  principals: ["user:alice", "role:engineer"], // ACL filter
  config: {
    search: { maxResults: 5, reranking: true },
  },
});
 
for (const result of results.results) {
  console.log(`[${result.confidence.toFixed(2)}] ${result.text}`);
  if (result.citations) {
    console.log(`  Source: ${result.citations.source} > ${result.citations.heading}`);
  }
}

await memory.ingestUrl(ctx, {
  orgId: "org_abc123",
  knowledgeBaseId: "kb_xyz",
  url: "https://docs.example.com/api-reference",
});

const uploadUrl = await memory.getUploadUrl(ctx);
// Use this URL to POST the file from your frontend

const result = await memory.processUploadedFile(ctx, {
  orgId: "org_abc123",
  knowledgeBaseId: "kb_xyz",
  storageId: "storage_abc",   // From the upload step
  fileName: "report.pdf",
});
// { success: true, chunkCount: 47, documentId: "doc_xyz" }

await memory.batchIngest(ctx, {
  orgId: "org_abc123",
  knowledgeBaseId: "kb_xyz",
  documents: [
    { text: "First document...", source: "doc1.md" },
    { text: "Second document...", source: "doc2.md" },
    { text: "Third document...", source: "doc3.md" },
  ],
});

await memory.addMemory(ctx, {
  orgId: "org_abc123",
  userId: "user_456",
  content: "Prefers TypeScript over JavaScript",
  type: "preference",  // "preference" | "fact" | "context" | "summary"
});

const memories = await memory.listMemories(ctx, {
  orgId: "org_abc123",
  userId: "user_456",
});
 
for (const mem of memories) {
  console.log(`[${mem.type}] ${mem.content} (strength: ${mem.strength})`);
}

await memory.deleteDocument(ctx, {
  orgId: "org_abc123",
  documentId: "doc_xyz",
});

await memory.deleteKnowledgeBase(ctx, {
  orgId: "org_abc123",
  knowledgeBaseId: "kb_xyz",
});

await memory.setDocumentAcl(ctx, {
  orgId: "org_abc123",
  documentId: "doc_xyz",
  principals: ["user:alice", "role:admin", "group:engineering"],
});

const logs = await memory.getAuditLog(ctx, {
  orgId: "org_abc123",
  action: "search",        // Optional: filter by action type
  actor: "user:alice",     // Optional: filter by actor
  after: Date.now() - 86400000, // Optional: time range
  limit: 100,
});

await memory.setQuota(ctx, {
  orgId: "org_abc123",
  quotas: {
    searchesPerDay: 1000,
    ingestionsPerDay: 100,
    maxDocuments: 500,
    maxStorageBytes: 1073741824,
  },
});

const status = await memory.getQuotaStatus(ctx, {
  orgId: "org_abc123",
});
 
console.log(`Searches: ${status.searches.used}/${status.searches.limit}`);
console.log(`Documents: ${status.documents.used}/${status.documents.limit}`);

try {
  const results = await memory.getContext(ctx, { orgId, query: "..." });
  return results;
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error);
 
  if (msg.includes("Quota exceeded")) {
    // Graceful degradation
    return { results: [], error: "Rate limit reached" };
  }
  if (msg.includes("not found")) {
    // Resource doesn't exist
    return { results: [], error: "Resource not found" };
  }
  // Unexpected error — rethrow
  throw error;
}