API Reference

Info

Last Updated: 2026-01-25 | Version: v0.35.1+

Complete API documentation for @cortexmemory/vercel-ai-provider (SDK v0.21.0+)

createCortexMemory(config)

Creates a memory-augmented model factory with manual memory control methods.

Signature

function createCortexMemory(config: CortexMemoryConfig): CortexMemoryModel;

Parameters

CortexMemoryConfig

Parameter	Type	Required	Default	Description
convexUrl	string	Yes	—	Convex deployment URL
memorySpaceId	string	Yes	—	Memory space for isolation
userId	string | () => string | Promise<string>	Yes	—	User ID (static or function)
agentId	string	Yes	—	Agent ID (required v0.17.0+)
userName	string	No	—	Display name for user. Default: 'User'
agentName	string	No	—	Display name for agent. Default: agentId
conversationId	string | () => string	No	—	Conversation ID. Default: auto-generated
embeddingProvider	object	No	—	Custom embedding provider
memorySearchLimit	number	No	—	Max memories to retrieve. Default: 5
minMemoryRelevance	number	No	—	Min relevance score (0-1). Default: 0.7
enableMemorySearch	boolean	No	—	Auto-search before generation. Default: true
enableMemoryStorage	boolean	No	—	Auto-store after generation. Default: true
contextInjectionStrategy	'system' | 'user' | 'custom'	No	—	Where to inject context. Default: 'system'
customContextBuilder	function	No	—	Custom context formatter
enableFactExtraction	boolean	No	—	Extract facts from conversations. Default: false
factExtractionConfig	object	No	—	Fact extraction configuration
extractFacts	function	No	—	Custom fact extraction
enableGraphMemory	boolean	No	—	Sync to graph database. Default: false
graphConfig	object	No	—	Graph database configuration
hiveMode	object	No	—	Cross-app memory config
defaultImportance	number	No	—	Default importance (0-100). Default: 50
defaultTags	string[]	No	—	Default tags. Default: []
streamingOptions	object	No	—	Streaming enhancement options
streamingHooks	object	No	—	Real-time streaming callbacks
beliefRevision	object | false	No	—	Belief revision configuration
enableStreamMetrics	boolean	No	—	Enable streaming metrics. Default: true
layerObserver	object	No	—	Layer orchestration observer
debug	boolean	No	—	Enable debug logging. Default: false
logger	object	No	—	Custom logger. Default: console

factExtractionConfig

factExtractionConfig?: {
  model?: string;      // Override fact extraction model (default: gpt-4o-mini)
  provider?: 'openai' | 'anthropic';  // Provider to use
}

graphConfig

graphConfig?: {
  uri?: string;        // Graph database URI
  username?: string;   // Graph database username
  password?: string;   // Graph database password
  type?: 'neo4j' | 'memgraph';  // Database type
}

streamingOptions

streamingOptions?: {
  storePartialResponse?: boolean;      // Store during streaming
  partialResponseInterval?: number;    // Update interval (ms)
  progressiveFactExtraction?: boolean; // Extract facts incrementally
  factExtractionThreshold?: number;    // Characters per extraction
  progressiveGraphSync?: boolean;      // Sync graph incrementally
  graphSyncInterval?: number;          // Graph sync interval (ms)
  partialFailureHandling?: 'store-partial' | 'rollback' | 'retry' | 'best-effort';
  maxRetries?: number;                 // Max retry attempts
  generateResumeToken?: boolean;       // Generate resume tokens
  streamTimeout?: number;              // Timeout (ms)
  maxResponseLength?: number;          // Max response length
  enableAdaptiveProcessing?: boolean;  // Auto-optimize processing
}

streamingHooks

streamingHooks?: {
  onChunk?: (event: {
    chunk: string;
    chunkNumber: number;
    accumulated: string;
    timestamp: number;
    estimatedTokens: number;
  }) => void | Promise<void>;
  onProgress?: (event: {
    bytesProcessed: number;
    chunks: number;
    elapsedMs: number;
    estimatedCompletion?: number;
    currentPhase?: "streaming" | "fact-extraction" | "storage" | "finalization";
  }) => void | Promise<void>;
  onError?: (error: {
    message: string;
    code?: string;
    phase?: string;
    recoverable?: boolean;
    resumeToken?: string;
  }) => void | Promise<void>;
  onComplete?: (event: {
    fullResponse: string;
    totalChunks: number;
    durationMs: number;
    factsExtracted: number;
  }) => void | Promise<void>;
}

beliefRevision

beliefRevision?: {
  enabled?: boolean;        // Enable belief revision
  slotMatching?: boolean;   // Enable slot matching
  llmResolution?: boolean;  // Enable LLM-based resolution
} | false;

layerObserver

layerObserver?: {
  /** Called when recall phase starts (context retrieval) */
  onRecallStart?: (orchestrationId: string) => void | Promise<void>;
  /** Called when recall phase completes */
  onRecallComplete?: (summary: RecallSummary) => void | Promise<void>;
  /** Called when remember phase starts (memory storage) */
  onRememberStart?: (orchestrationId: string) => void | Promise<void>;
  /** Called when remember phase completes */
  onRememberComplete?: (summary: OrchestrationSummary) => void | Promise<void>;
  /** Called on any layer status change (includes phase info) */
  onLayerUpdate?: (event: LayerEvent) => void | Promise<void>;
}

Returns

CortexMemoryModel

A function that wraps language models + manual memory methods:

interface CortexMemoryModel {
  // Model wrapping
  (model: LanguageModelV1): LanguageModelV1;

  // Manual memory methods
  search(query: string, options?: SearchOptions): Promise<MemoryEntry[]>;
  remember(
    userMsg: string,
    agentResp: string,
    options?: RememberOptions,
  ): Promise<void>;
  getMemories(options?: { limit?: number }): Promise<MemoryEntry[]>;
  clearMemories(options?: ClearOptions): Promise<number>;
  getConfig(): Readonly<CortexMemoryConfig>;
}

createCortexMemoryAsync(config)

Async version for automatic graph database configuration from environment variables.

Signature

async function createCortexMemoryAsync(
  config: CortexMemoryConfig,
): Promise<CortexMemoryModel>;

Example

// Reads graph config from NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD
const cortexMemory = await createCortexMemoryAsync({
  convexUrl: process.env.CONVEX_URL!,
  memorySpaceId: "smart-agent",
  userId: "user-123",
  agentId: "my-assistant",
});

Model Wrapping

Syntax

const wrappedModel = cortexMemory(underlyingModel);

Examples

import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";
import { google } from "@ai-sdk/google";

const cortexMemory = createCortexMemory({
  convexUrl: process.env.CONVEX_URL!,
  memorySpaceId: "my-agent",
  userId: "user-123",
  agentId: "my-assistant", // Required!
});

// Wrap any AI SDK provider
const gpt4 = cortexMemory(openai("gpt-4o-mini"));
const claude = cortexMemory(anthropic("claude-3-opus"));
const gemini = cortexMemory(google("gemini-pro"));

// Use with AI SDK functions
await streamText({ model: gpt4, messages });
await generateText({ model: claude, messages });
await generateObject({ model: gemini, prompt, schema });

Manual Memory Methods

search(query, options?)

Search memories manually.

async search(
  query: string,
  options?: {
    limit?: number;
    minScore?: number;
    tags?: string[];
    userId?: string;
    embedding?: number[];
    sourceType?: 'conversation' | 'system' | 'tool' | 'a2a';
    minImportance?: number;
  }
): Promise<MemoryEntry[]>

Example:

const memories = await cortexMemory.search("user preferences", {
  limit: 10,
  minScore: 0.8,
  tags: ["important"],
});

console.log(memories);
// [{ content: '...', metadata: {...}, ... }]

remember(userMessage, agentResponse, options?)

Store a conversation manually.

async remember(
  userMessage: string,
  agentResponse: string,
  options?: {
    conversationId?: string;
    generateEmbedding?: (text: string) => Promise<number[]>;
    extractFacts?: (userMsg: string, agentResp: string) => Promise<Fact[]>;
    // Note: syncToGraph removed in v0.29.0+ - sync is automatic when CORTEX_GRAPH_SYNC=true
  }
): Promise<void>

Example:

// Graph sync is automatic when CORTEX_GRAPH_SYNC=true (v0.29.0+)
await cortexMemory.remember(
  "My favorite color is blue",
  "I will remember that!",
  {
    conversationId: "conv-123",
    // No syncToGraph needed - sync is automatic
  },
);

getMemories(options?)

Get all memories (paginated).

async getMemories(
  options?: {
    limit?: number;
  }
): Promise<MemoryEntry[]>

Example:

const all = await cortexMemory.getMemories({ limit: 100 });
console.log(`Total memories: ${all.length}`);

clearMemories(options)

Clear memories (requires confirmation).

async clearMemories(
  options: {
    confirm: boolean;
    userId?: string;
    sourceType?: 'conversation' | 'system' | 'tool' | 'a2a';
  }
): Promise<number>

Example:

// Clear all memories
const deleted = await cortexMemory.clearMemories({ confirm: true });
console.log(`Deleted ${deleted} memories`);

// Clear specific user's memories
await cortexMemory.clearMemories({
  confirm: true,
  userId: "user-123",
});

getConfig()

Get current configuration (read-only).

getConfig(): Readonly<CortexMemoryConfig>

Example:

const config = cortexMemory.getConfig();
console.log(`Memory Space: ${config.memorySpaceId}`);
console.log(`Agent: ${config.agentId}`);

Types

MemoryEntry

interface MemoryEntry {
  _id: string;                    // Internal ID
  memoryId: string;                // Memory identifier
  memorySpaceId: string;           // Memory space for isolation
  tenantId?: string;               // Tenant identifier
  participantId?: string;           // Participant identifier
  userId?: string;                 // User identifier
  agentId?: string;                // Agent identifier
  content: string;                 // Memory content
  contentType: ContentType;        // Content type classification
  embedding?: number[];            // Vector embedding
  sourceType: "conversation" | "system" | "tool" | "a2a";
  sourceUserId?: string;           // Source user ID
  sourceUserName?: string;         // Source user name
  sourceTimestamp: number;         // Source timestamp
  messageRole?: "user" | "agent" | "system";
  conversationRef?: ConversationRef;
  immutableRef?: ImmutableRef;
  mutableRef?: MutableRef;
  factsRef?: FactsRef;
  importance: number;              // 0-100
  tags: string[];                  // Tags for categorization
  enrichedContent?: string;        // Enriched/processed content
  factCategory?: string;           // Fact category classification
  version: number;                 // Version number
  previousVersions: MemoryVersion[]; // Version history
  createdAt: number;               // Creation timestamp
  updatedAt: number;               // Last update timestamp
  lastAccessed?: number;           // Last access timestamp
  accessCount: number;             // Access count
}

LayerEvent

interface LayerEvent {
  layer:
    | "memorySpace"
    | "user"
    | "agent"
    | "context"      // NEW in v0.35.1: Context assembly layer
    | "conversation"
    | "vector"
    | "facts"
    | "graph";
  status: "pending" | "in_progress" | "complete" | "error" | "skipped";
  timestamp: number;
  /** NEW in v0.35.1: Phase this event belongs to */
  phase: "recall" | "remember";
  latencyMs?: number;
  data?: {
    id?: string;
    preview?: string;
    metadata?: Record<string, unknown>;
  };
  error?: {
    message: string;
    code?: string;
  };
}

RecallSummary

NEW in v0.35.1 - Summary of the recall (context retrieval) phase:

interface RecallSummary {
  orchestrationId: string;
  phase: "recall";
  totalLatencyMs: number;
  layers: Partial<Record<MemoryLayer, LayerEvent>>;
  /** Retrieved context ready for LLM injection */
  context: {
    formatted?: string;
    memoriesCount: number;
    factsCount: number;
    graphEntitiesCount: number;
  };
}

OrchestrationSummary

Summary of the remember (memory storage) phase:

interface OrchestrationSummary {
  orchestrationId: string;
  phase: "remember";
  totalLatencyMs: number;
  layers: Record<MemoryLayer, LayerEvent>;
  createdIds: {
    conversationId?: string;
    memoryIds?: string[];
    factIds?: string[];
  };
}

---

useLayerTracking Hook

NEW in v0.35.1 - React hook for phase-aware layer tracking.

import { useLayerTracking } from "@cortexmemory/vercel-ai-provider/react";

Returns

interface UseLayerTrackingResult {
  // Phase-Specific State (New API - recommended)
  recallLayers: Record<MemoryLayer, LayerState>;
  rememberLayers: Record<MemoryLayer, LayerState>;
  isRecalling: boolean;
  isRemembering: boolean;
  recallOrchestrationId?: string;
  rememberOrchestrationId?: string;

  // Backward-Compatible State (deprecated)
  layers: Record<MemoryLayer, LayerState>;  // Combined view
  isOrchestrating: boolean;  // isRecalling || isRemembering
  orchestrationId?: string;

  // Phase-Specific Methods (New API)
  startRecall: (orchestrationId?: string) => void;
  startRemember: (orchestrationId?: string) => void;
  resetRecall: () => void;
  resetRemember: () => void;
  updatePhaseLayer: (phase, layer, status, data?, revisionInfo?) => void;

  // Backward-Compatible Methods
  startOrchestration: (orchestrationId?: string) => void;  // deprecated
  updateLayer: (layer, status, data?, revisionInfo?) => void;  // deprecated
  resetLayers: () => void;
  handleDataPart: (dataPart: unknown) => void;  // For useChat onData
}

Example Usage

import { useLayerTracking } from "@cortexmemory/vercel-ai-provider/react";
import { useChat } from "@ai-sdk/react";

function ChatComponent() {
  const {
    recallLayers,
    rememberLayers,
    isRecalling,
    isRemembering,
    handleDataPart,
  } = useLayerTracking();

  const { messages, sendMessage } = useChat({
    onData: handleDataPart,  // Automatically parses phase-aware events
  });

  return (
    <div>
      {isRecalling && (
        <div className="recall-progress">
          <p>Retrieving context...</p>
          <LayerProgress layers={recallLayers} />
        </div>
      )}
      {isRemembering && (
        <div className="remember-progress">
          <p>Saving memories...</p>
          <LayerProgress layers={rememberLayers} />
        </div>
      )}
      <Messages messages={messages} />
    </div>
  );
}

Layer Constants

// Layers involved in recall phase
export const RECALL_LAYERS: MemoryLayer[] = [
  "memorySpace", "user", "agent", "context"
];

// Layers involved in remember phase
export const REMEMBER_LAYERS: MemoryLayer[] = [
  "conversation", "vector", "facts", "graph"
];

---

Exported Types

export type {
  CortexMemoryConfig,
  CortexMemoryModel,
  ManualMemorySearchOptions,
  ManualRememberOptions,
  ManualClearOptions,
  ContextInjectionStrategy,
  SupportedProvider,
  LayerObserver,
  LayerEvent,
  LayerStatus,
  MemoryLayer,
  OrchestrationSummary,
  RecallSummary,           // NEW in v0.35.1
  OrchestrationPhase,      // NEW in v0.35.1
  RevisionAction,
} from "@cortexmemory/vercel-ai-provider";

// React hook exports
export {
  useLayerTracking,        // NEW in v0.35.1
  RECALL_LAYERS,           // NEW in v0.35.1
  REMEMBER_LAYERS,         // NEW in v0.35.1
} from "@cortexmemory/vercel-ai-provider/react";

Info

AI SDK v6 compatibility layer APIs (including isV6Available, createMemoryPrepareCall, CortexCallOptions, etc.) are supported. The Vercel AI Provider is compatible with AI SDK versions 3, 4, 5, and 6.

Next Steps