@vellumai/assistant 0.3.0

package/src/memory/qdrant-client.ts

@@ -0,0 +1,366 @@
+import { QdrantClient as QdrantRestClient } from '@qdrant/js-client-rest';
+import { v4 as uuid } from 'uuid';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('qdrant-client');
+
+export interface QdrantClientConfig {
+  url: string;
+  collection: string;
+  vectorSize: number;
+  onDisk: boolean;
+  quantization: 'scalar' | 'none';
+}
+
+export interface QdrantPointPayload {
+  target_type: 'segment' | 'item' | 'summary';
+  target_id: string;
+  text: string;
+  kind?: string;
+  subject?: string;
+  status?: string;
+  importance?: number;
+  confidence?: number;
+  created_at: number;
+  last_seen_at?: number;
+  conversation_id?: string;
+  message_id?: string;
+  entity_ids?: string[];
+}
+
+export interface QdrantSearchResult {
+  id: string;
+  score: number;
+  payload: QdrantPointPayload;
+}
+
+let _instance: VellumQdrantClient | null = null;
+
+export function getQdrantClient(): VellumQdrantClient {
+  if (!_instance) {
+    throw new Error('Qdrant client not initialized. Call initQdrantClient() first.');
+  }
+  return _instance;
+}
+
+export function initQdrantClient(config: QdrantClientConfig): VellumQdrantClient {
+  _instance = new VellumQdrantClient(config);
+  return _instance;
+}
+
+export class VellumQdrantClient {
+  private readonly client: QdrantRestClient;
+  private readonly collection: string;
+  private readonly vectorSize: number;
+  private readonly onDisk: boolean;
+  private readonly quantization: 'scalar' | 'none';
+  private collectionReady = false;
+
+  constructor(config: QdrantClientConfig) {
+    this.client = new QdrantRestClient({ url: config.url, checkCompatibility: false });
+    this.collection = config.collection;
+    this.vectorSize = config.vectorSize;
+    this.onDisk = config.onDisk;
+    this.quantization = config.quantization;
+  }
+
+  async ensureCollection(): Promise<void> {
+    if (this.collectionReady) return;
+
+    try {
+      const exists = await this.client.collectionExists(this.collection);
+      if (exists.exists) {
+        this.collectionReady = true;
+        return;
+      }
+    } catch {
+      // Collection doesn't exist, create it
+    }
+
+    log.info({ collection: this.collection, vectorSize: this.vectorSize }, 'Creating Qdrant collection');
+
+    await this.client.createCollection(this.collection, {
+      vectors: {
+        size: this.vectorSize,
+        distance: 'Cosine',
+        on_disk: this.onDisk,
+      },
+      hnsw_config: {
+        on_disk: this.onDisk,
+        m: 16,
+        ef_construct: 100,
+      },
+      quantization_config: this.quantization === 'scalar'
+        ? {
+          scalar: {
+            type: 'int8',
+            quantile: 0.99,
+            always_ram: true,
+          },
+        }
+        : undefined,
+      on_disk_payload: this.onDisk,
+    });
+
+    // Create payload indexes for efficient filtering
+    await Promise.all([
+      this.client.createPayloadIndex(this.collection, {
+        field_name: 'target_type',
+        field_schema: 'keyword',
+      }),
+      this.client.createPayloadIndex(this.collection, {
+        field_name: 'target_id',
+        field_schema: 'keyword',
+      }),
+      this.client.createPayloadIndex(this.collection, {
+        field_name: 'kind',
+        field_schema: 'keyword',
+      }),
+      this.client.createPayloadIndex(this.collection, {
+        field_name: 'status',
+        field_schema: 'keyword',
+      }),
+      this.client.createPayloadIndex(this.collection, {
+        field_name: 'created_at',
+        field_schema: 'integer',
+      }),
+      this.client.createPayloadIndex(this.collection, {
+        field_name: 'conversation_id',
+        field_schema: 'keyword',
+      }),
+    ]);
+
+    this.collectionReady = true;
+    log.info({ collection: this.collection }, 'Qdrant collection created with payload indexes');
+  }
+
+  async upsert(
+    targetType: 'segment' | 'item' | 'summary',
+    targetId: string,
+    vector: number[],
+    payload: Omit<QdrantPointPayload, 'target_type' | 'target_id'>,
+  ): Promise<string> {
+    await this.ensureCollection();
+
+    // Deterministic point ID: look up existing point by target_type + target_id
+    const existing = await this.findByTarget(targetType, targetId);
+    const pointId = existing ?? uuid();
+
+    try {
+      await this.client.upsert(this.collection, {
+        wait: true,
+        points: [
+          {
+            id: pointId,
+            vector,
+            payload: {
+              target_type: targetType,
+              target_id: targetId,
+              ...payload,
+            },
+          },
+        ],
+      });
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        await this.client.upsert(this.collection, {
+          wait: true,
+          points: [
+            {
+              id: pointId,
+              vector,
+              payload: {
+                target_type: targetType,
+                target_id: targetId,
+                ...payload,
+              },
+            },
+          ],
+        });
+      } else {
+        throw err;
+      }
+    }
+
+    return pointId;
+  }
+
+  async search(
+    vector: number[],
+    limit: number,
+    filter?: Record<string, unknown>,
+  ): Promise<QdrantSearchResult[]> {
+    await this.ensureCollection();
+
+    let results;
+    try {
+      results = await this.client.search(this.collection, {
+        vector,
+        limit,
+        with_payload: true,
+        score_threshold: 0.0,
+        filter: filter as Parameters<QdrantRestClient['search']>[1]['filter'],
+      });
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        results = await this.client.search(this.collection, {
+          vector,
+          limit,
+          with_payload: true,
+          score_threshold: 0.0,
+          filter: filter as Parameters<QdrantRestClient['search']>[1]['filter'],
+        });
+      } else {
+        throw err;
+      }
+    }
+
+    return results.map((result) => ({
+      id: typeof result.id === 'string' ? result.id : String(result.id),
+      score: result.score,
+      payload: result.payload as unknown as QdrantPointPayload,
+    }));
+  }
+
+  async searchWithFilter(
+    vector: number[],
+    limit: number,
+    targetTypes: Array<'segment' | 'item' | 'summary'>,
+    excludeMessageIds?: string[],
+  ): Promise<QdrantSearchResult[]> {
+    const mustConditions: Array<Record<string, unknown>> = [
+      {
+        key: 'target_type',
+        match: { any: targetTypes },
+      },
+    ];
+
+    if (excludeMessageIds && excludeMessageIds.length > 0) {
+      // Only require status=active for items; segments and summaries don't have a status field
+      mustConditions.push({
+        should: [
+          {
+            must: [
+              { key: 'target_type', match: { value: 'item' } },
+              { key: 'status', match: { value: 'active' } },
+            ],
+          },
+          { key: 'target_type', match: { any: ['segment', 'summary'] } },
+        ],
+      });
+    }
+
+    const mustNotConditions: Array<Record<string, unknown>> = [];
+    if (excludeMessageIds && excludeMessageIds.length > 0) {
+      mustNotConditions.push({
+        key: 'message_id',
+        match: { any: excludeMessageIds },
+      });
+    }
+
+    const filter: Record<string, unknown> = {
+      must: mustConditions,
+    };
+    if (mustNotConditions.length > 0) {
+      filter.must_not = mustNotConditions;
+    }
+
+    return this.search(vector, limit, filter);
+  }
+
+  async deleteByTarget(targetType: string, targetId: string): Promise<void> {
+    await this.ensureCollection();
+
+    const doDelete = () => this.client.delete(this.collection, {
+      wait: true,
+      filter: {
+        must: [
+          { key: 'target_type', match: { value: targetType } },
+          { key: 'target_id', match: { value: targetId } },
+        ],
+      },
+    });
+
+    try {
+      await doDelete();
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        await doDelete();
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  async count(): Promise<number> {
+    await this.ensureCollection();
+
+    try {
+      const result = await this.client.count(this.collection, { exact: false });
+      return result.count;
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        const result = await this.client.count(this.collection, { exact: false });
+        return result.count;
+      }
+      throw err;
+    }
+  }
+
+  async deleteCollection(): Promise<boolean> {
+    try {
+      const exists = await this.client.collectionExists(this.collection);
+      if (!exists.exists) return false;
+      await this.client.deleteCollection(this.collection);
+      this.collectionReady = false;
+      return true;
+    } catch (err) {
+      log.warn({ err, collection: this.collection }, 'Failed to delete Qdrant collection');
+      return false;
+    }
+  }
+
+  /**
+   * Detect "collection not found" errors from Qdrant so callers can
+   * reset collectionReady and retry after an external deletion
+   * (e.g. `vellum sessions clear`).
+   */
+  private isCollectionMissing(err: unknown): boolean {
+    if (err && typeof err === 'object' && 'status' in err && (err as { status: number }).status === 404) {
+      return true;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.includes('Not found') || msg.includes('doesn\'t exist') || msg.includes('not found');
+  }
+
+  private async findByTarget(targetType: string, targetId: string): Promise<string | null> {
+    try {
+      const results = await this.client.scroll(this.collection, {
+        filter: {
+          must: [
+            { key: 'target_type', match: { value: targetType } },
+            { key: 'target_id', match: { value: targetId } },
+          ],
+        },
+        limit: 1,
+        with_payload: false,
+        with_vector: false,
+      });
+      if (results.points.length > 0) {
+        const id = results.points[0].id;
+        return typeof id === 'string' ? id : String(id);
+      }
+    } catch {
+      // Not found
+    }
+    return null;
+  }
+}

package/src/memory/qdrant-manager.ts

@@ -0,0 +1,242 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { arch, platform } from 'node:os';
+import type { Subprocess } from 'bun';
+import { getLogger } from '../util/logger.js';
+import { getDataDir } from '../util/platform.js';
+
+const log = getLogger('qdrant-manager');
+
+const QDRANT_VERSION = '1.13.2';
+const READYZ_POLL_INTERVAL_MS = 200;
+const READYZ_TIMEOUT_MS = 30_000;
+const SHUTDOWN_GRACE_MS = 5_000;
+
+export interface QdrantManagerConfig {
+  url: string;
+  storagePath?: string;
+}
+
+/**
+ * Manages the Qdrant sidecar process lifecycle.
+ *
+ * Desktop: spawns ~/.vellum/bin/qdrant as a child process.
+ * K8s / external: connects to an existing Qdrant at the configured URL.
+ *
+ * Detection logic:
+ * - If QDRANT_URL env var is set → external mode (don't spawn)
+ * - If qdrant binary exists at ~/.vellum/bin/qdrant → local spawn mode
+ * - Otherwise → external mode (assume sidecar or remote)
+ */
+export class QdrantManager {
+  private process: Subprocess | null = null;
+  private readonly url: string;
+  private readonly host: string;
+  private readonly port: number;
+  private readonly storagePath: string;
+  private readonly pidPath: string;
+  private readonly isExternal: boolean;
+
+  constructor(config: QdrantManagerConfig) {
+    this.url = config.url;
+    const parsed = new URL(config.url);
+    this.host = parsed.hostname;
+    this.port = parseInt(parsed.port || '6333', 10);
+    this.storagePath = config.storagePath ?? join(getDataDir(), 'qdrant');
+    this.pidPath = join(getDataDir(), 'qdrant', 'qdrant.pid');
+
+    // External mode only if QDRANT_URL is explicitly set
+    this.isExternal = Boolean(process.env.QDRANT_URL?.trim());
+  }
+
+  async start(): Promise<void> {
+    if (this.isExternal) {
+      log.info({ url: this.url }, 'Qdrant running in external mode, verifying connectivity');
+      await this.waitForReady();
+      return;
+    }
+
+    // Check for stale process
+    this.cleanupStaleProcess();
+
+    const binaryPath = this.getBinaryPath();
+    if (!existsSync(binaryPath)) {
+      await this.installBinary(binaryPath);
+    }
+
+    log.info({ binaryPath, storagePath: this.storagePath, port: this.port }, 'Starting Qdrant');
+
+    this.process = Bun.spawn({
+      cmd: [binaryPath],
+      env: {
+        ...process.env,
+        QDRANT__SERVICE__HOST: this.host,
+        QDRANT__SERVICE__HTTP_PORT: String(this.port),
+        QDRANT__SERVICE__GRPC_PORT: '0', // disable gRPC
+        QDRANT__TELEMETRY_DISABLED: 'true',
+        QDRANT__STORAGE__STORAGE_PATH: this.storagePath,
+        QDRANT__LOG_LEVEL: 'WARN',
+      },
+      stdout: 'ignore',
+      stderr: 'ignore',
+    });
+
+    if (this.process.pid) {
+      this.writePid(this.process.pid);
+    }
+
+    try {
+      await this.waitForReady();
+      log.info({ pid: this.process.pid, port: this.port }, 'Qdrant is ready');
+    } catch (err) {
+      // If startup fails, clean up
+      await this.stop();
+      throw err;
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (!this.process) {
+      this.cleanupPid();
+      return;
+    }
+
+    log.info('Stopping Qdrant');
+    this.process.kill('SIGTERM');
+
+    // Wait for graceful shutdown
+    const graceful = await Promise.race([
+      this.process.exited.then(() => true),
+      new Promise<false>((resolve) => setTimeout(() => resolve(false), SHUTDOWN_GRACE_MS)),
+    ]);
+
+    if (!graceful) {
+      log.warn('Qdrant did not exit gracefully, sending SIGKILL');
+      this.process.kill('SIGKILL');
+      await this.process.exited;
+    }
+
+    this.process = null;
+    this.cleanupPid();
+    log.info('Qdrant stopped');
+  }
+
+  getUrl(): string {
+    return this.url;
+  }
+
+  private async installBinary(binaryPath: string): Promise<void> {
+    const os = platform();
+    const cpu = arch();
+
+    let target: string;
+    if (os === 'darwin' && cpu === 'arm64') {
+      target = 'aarch64-apple-darwin';
+    } else if (os === 'darwin' && cpu === 'x64') {
+      target = 'x86_64-apple-darwin';
+    } else if (os === 'linux' && cpu === 'x64') {
+      target = 'x86_64-unknown-linux-musl';
+    } else if (os === 'linux' && cpu === 'arm64') {
+      target = 'aarch64-unknown-linux-musl';
+    } else {
+      throw new Error(
+        `Unsupported platform: ${os}/${cpu}. ` +
+        'Set QDRANT_URL to use an external Qdrant instance.',
+      );
+    }
+
+    const filename = `qdrant-${target}.tar.gz`;
+    const url = `https://github.com/qdrant/qdrant/releases/download/v${QDRANT_VERSION}/${filename}`;
+    log.info({ url, binaryPath }, 'Downloading Qdrant binary');
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to download Qdrant: ${response.status} ${response.statusText} from ${url}`);
+    }
+
+    const tarball = await response.arrayBuffer();
+
+    // Extract the qdrant binary from the tarball
+    const binDir = dirname(binaryPath);
+    mkdirSync(binDir, { recursive: true });
+
+    // Write tarball to temp file, extract with tar
+    const tmpTar = join(binDir, `qdrant-download-${Date.now()}.tar.gz`);
+    writeFileSync(tmpTar, Buffer.from(tarball));
+
+    try {
+      const proc = Bun.spawn({
+        cmd: ['tar', 'xzf', tmpTar, '-C', binDir, 'qdrant'],
+        stdout: 'ignore',
+        stderr: 'pipe',
+      });
+      await proc.exited;
+      if (proc.exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        throw new Error(`Failed to extract Qdrant binary: ${stderr}`);
+      }
+    } finally {
+      try { unlinkSync(tmpTar); } catch { /* ignore */ }
+    }
+
+    chmodSync(binaryPath, 0o755);
+    log.info({ binaryPath, version: QDRANT_VERSION }, 'Qdrant binary installed');
+  }
+
+  private async waitForReady(): Promise<void> {
+    const start = Date.now();
+    while (Date.now() - start < READYZ_TIMEOUT_MS) {
+      try {
+        const res = await fetch(`${this.url}/readyz`);
+        if (res.ok) return;
+      } catch {
+        // Not ready yet
+      }
+      await Bun.sleep(READYZ_POLL_INTERVAL_MS);
+    }
+    throw new Error(`Qdrant did not become ready within ${READYZ_TIMEOUT_MS}ms at ${this.url}`);
+  }
+
+  private getBinaryPath(): string {
+    return join(getDataDir(), 'qdrant', 'bin', 'qdrant');
+  }
+
+  private cleanupStaleProcess(): void {
+    const pid = this.readPid();
+    if (pid === null) return;
+
+    try {
+      process.kill(pid, 0); // Check if process exists
+      // Process is still running — kill it
+      log.warn({ pid }, 'Found stale Qdrant process, killing it');
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // Process doesn't exist, just clean up PID file
+    }
+    this.cleanupPid();
+  }
+
+  private readPid(): number | null {
+    if (!existsSync(this.pidPath)) return null;
+    try {
+      const pid = parseInt(readFileSync(this.pidPath, 'utf-8').trim(), 10);
+      return isNaN(pid) ? null : pid;
+    } catch {
+      return null;
+    }
+  }
+
+  private writePid(pid: number): void {
+    writeFileSync(this.pidPath, String(pid));
+  }
+
+  private cleanupPid(): void {
+    if (existsSync(this.pidPath)) {
+      try {
+        unlinkSync(this.pidPath);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+}

package/src/memory/query-builder.ts

@@ -0,0 +1,45 @@
+import { getSummaryFromContextMessage } from '../context/window-manager.js';
+import type { Message } from '../providers/types.js';
+
+const TRUNCATION_MARKER = '<truncated />';
+
+export interface MemoryQueryBuilderOptions {
+  maxUserRequestChars?: number;
+  maxSessionSummaryChars?: number;
+}
+
+/**
+ * Build a deterministic memory recall query string from the current user
+ * request plus any in-context session summary message.
+ */
+export function buildMemoryQuery(
+  userRequest: string,
+  messages: Message[],
+  options?: MemoryQueryBuilderOptions,
+): string {
+  const maxUserRequestChars = options?.maxUserRequestChars ?? 2000;
+  const maxSessionSummaryChars = options?.maxSessionSummaryChars ?? 1200;
+
+  const requestText = clampSection(userRequest.trim(), maxUserRequestChars);
+  const sessionSummary = messages
+    .map((message) => getSummaryFromContextMessage(message))
+    .find((summary): summary is string => summary !== null);
+
+  const content = requestText.length > 0 ? requestText : '(empty)';
+
+  if (sessionSummary && sessionSummary.trim().length > 0) {
+    const compactSummary = clampSection(sessionSummary.trim(), maxSessionSummaryChars);
+    return `${content}\n\nContext summary:\n${compactSummary}`;
+  }
+
+  return content;
+}
+
+function clampSection(value: string, maxChars: number): string {
+  if (maxChars <= 0) return '';
+  if (value.length <= maxChars) return value;
+  const half = Math.floor((maxChars - TRUNCATION_MARKER.length) / 2);
+  if (half <= 0) return value.slice(0, maxChars);
+  return value.slice(0, half) + TRUNCATION_MARKER + value.slice(-half);
+}
+

package/src/memory/retrieval-budget.ts

@@ -0,0 +1,30 @@
+export interface RecallBudgetInput {
+  estimatedPromptTokens: number;
+  maxInputTokens: number;
+  targetHeadroomTokens: number;
+  minInjectTokens: number;
+  maxInjectTokens: number;
+}
+
+/**
+ * Compute per-turn memory recall injection budget from context headroom.
+ *
+ * The result is always clamped into [minInjectTokens, maxInjectTokens].
+ */
+export function computeRecallBudget(input: RecallBudgetInput): number {
+  const maxInput = Math.max(0, Math.floor(input.maxInputTokens));
+  const estimatedPrompt = Math.max(0, Math.floor(input.estimatedPromptTokens));
+  const headroomTarget = Math.max(0, Math.floor(input.targetHeadroomTokens));
+  const minInject = Math.max(1, Math.floor(input.minInjectTokens));
+  const maxInject = Math.max(minInject, Math.floor(input.maxInjectTokens));
+
+  const available = maxInput - estimatedPrompt - headroomTarget;
+  return clamp(Math.floor(available), minInject, maxInject);
+}
+
+function clamp(value: number, min: number, max: number): number {
+  if (value < min) return min;
+  if (value > max) return max;
+  return value;
+}
+