@vellumai/assistant 0.4.48 → 0.4.50

package/src/tools/credentials/metadata-store.ts

@@ -4,6 +4,11 @@
  * Persists non-secret metadata about credentials (policy, timestamps, IDs)
  * in a versioned JSON file under protected storage. Secret values remain
  * in the secure key backend only.
+ *
+ * OAuth-specific fields (expiresAt, grantedScopes, oauth2TokenUrl,
+ * oauth2ClientId, oauth2TokenEndpointAuthMethod, hasRefreshToken) are now
+ * exclusively managed by the SQLite oauth-store and have been removed
+ * from this interface as of v5.
  */
 
 import { randomUUID } from "node:crypto";
@@ -21,26 +26,16 @@ export interface CredentialMetadata {
   allowedTools: string[];
   allowedDomains: string[];
   usageDescription?: string;
-  expiresAt?: number;
-  grantedScopes?: string[];
-  /** OAuth2 token endpoint — enables autonomous token refresh without an IntegrationDefinition. */
-  oauth2TokenUrl?: string;
-  /** OAuth2 client ID — paired with oauth2TokenUrl for refresh. */
-  oauth2ClientId?: string;
-  /** How the client authenticates at the token endpoint (client_secret_basic or client_secret_post). */
-  oauth2TokenEndpointAuthMethod?: string;
   /** Human-friendly name for this credential (e.g. "fal-primary"). */
   alias?: string;
   /** Templates describing how to inject this credential into proxied requests. */
   injectionTemplates?: CredentialInjectionTemplate[];
-  /** Whether a refresh token exists in the secure store for this service. */
-  hasRefreshToken?: boolean;
   createdAt: number;
   updatedAt: number;
 }
 
 /** Current on-disk schema version. */
-const CURRENT_VERSION = 4;
+const CURRENT_VERSION = 5;
 
 interface MetadataFile {
   version: typeof CURRENT_VERSION;
@@ -88,9 +83,10 @@ function isValidCredentialRecord(
 }
 
 /**
- * Migrate a v1 record to v2 by backfilling new optional fields with defaults.
+ * Migrate any record to v5 by stripping OAuth-specific fields that are
+ * now exclusively managed by the SQLite oauth-store.
  */
-function migrateRecordV1toV2(
+function migrateRecordToV5(
   record: Record<string, unknown>,
 ): CredentialMetadata {
   return {
@@ -107,73 +103,15 @@ function migrateRecordV1toV2(
       typeof record.usageDescription === "string"
         ? record.usageDescription
         : undefined,
-    expiresAt:
-      typeof record.expiresAt === "number" ? record.expiresAt : undefined,
-    grantedScopes: Array.isArray(record.grantedScopes)
-      ? (record.grantedScopes as string[])
-      : undefined,
-    oauth2TokenUrl:
-      typeof record.oauth2TokenUrl === "string"
-        ? record.oauth2TokenUrl
-        : undefined,
-    oauth2ClientId:
-      typeof record.oauth2ClientId === "string"
-        ? record.oauth2ClientId
-        : undefined,
-    oauth2TokenEndpointAuthMethod:
-      typeof record.oauth2TokenEndpointAuthMethod === "string"
-        ? record.oauth2TokenEndpointAuthMethod
-        : undefined,
     alias: typeof record.alias === "string" ? record.alias : undefined,
     injectionTemplates: Array.isArray(record.injectionTemplates)
       ? (record.injectionTemplates as CredentialInjectionTemplate[])
       : undefined,
-    hasRefreshToken:
-      typeof record.hasRefreshToken === "boolean"
-        ? record.hasRefreshToken
-        : undefined,
     createdAt: record.createdAt as number,
     updatedAt: record.updatedAt as number,
   };
 }
 
-/**
- * Migrate a v2 record to v3 by stripping the oauth2ClientSecret field.
- * Client secrets are now read exclusively from the secure key store.
- */
-function migrateRecordV2toV3(record: CredentialMetadata): CredentialMetadata {
-  const { oauth2ClientSecret: _removed, ...rest } =
-    record as CredentialMetadata & { oauth2ClientSecret?: string };
-  return rest;
-}
-
-/**
- * Migrate v3 credentials to v4:
- * - Delete ghost `refresh_token` metadata records
- * - Set `hasRefreshToken: true` on corresponding `access_token` records
- */
-function migrateV3toV4(
-  credentials: CredentialMetadata[],
-): CredentialMetadata[] {
-  // Collect services that had refresh_token ghost records
-  const servicesWithRefresh = new Set<string>();
-  for (const c of credentials) {
-    if (c.field === "refresh_token") {
-      servicesWithRefresh.add(c.service);
-    }
-  }
-
-  // Remove all refresh_token records and set hasRefreshToken on access_token records
-  const filtered = credentials.filter((c) => c.field !== "refresh_token");
-  for (const c of filtered) {
-    if (c.field === "access_token" && servicesWithRefresh.has(c.service)) {
-      c.hasRefreshToken = true;
-    }
-  }
-
-  return filtered;
-}
-
 function loadFile(): LoadResult {
   const raw = readTextFileSync(getMetadataPath());
   if (raw == null) {
@@ -189,7 +127,8 @@ function loadFile(): LoadResult {
       fileVersion !== 1 &&
       fileVersion !== 2 &&
       fileVersion !== 3 &&
-      fileVersion !== 4
+      fileVersion !== 4 &&
+      fileVersion !== 5
     ) {
       // Unrecognized version (future, fractional, negative, zero) — refuse to touch it
       return { unknownVersion: true };
@@ -201,24 +140,12 @@ function loadFile(): LoadResult {
     const validRecords = rawCredentials.filter(isValidCredentialRecord);
 
     if (fileVersion < CURRENT_VERSION) {
-      // Apply migrations in sequence: v1→v2→v3→v4
-      let credentials: CredentialMetadata[];
-      if (fileVersion === 1) {
-        credentials = migrateV3toV4(
-          validRecords.map(migrateRecordV1toV2).map(migrateRecordV2toV3),
-        );
-      } else if (fileVersion === 2) {
-        credentials = migrateV3toV4(
-          (validRecords as unknown as CredentialMetadata[]).map(
-            migrateRecordV2toV3,
-          ),
-        );
-      } else {
-        // fileVersion === 3
-        credentials = migrateV3toV4(
-          validRecords as unknown as CredentialMetadata[],
-        );
-      }
+      // Migrate all older versions to v5 by stripping OAuth-specific fields
+      // and removing ghost refresh_token records
+      const filtered = validRecords.filter(
+        (r) => (r as Record<string, unknown>).field !== "refresh_token",
+      );
+      const credentials = filtered.map(migrateRecordToV5);
       const migrated: MetadataFile = { version: CURRENT_VERSION, credentials };
       try {
         saveFile(migrated);
@@ -272,17 +199,10 @@ export function upsertCredentialMetadata(
     allowedTools?: string[];
     allowedDomains?: string[];
     usageDescription?: string;
-    /** Pass `null` to explicitly clear a previously-set expiry. */
-    expiresAt?: number | null;
-    grantedScopes?: string[];
-    oauth2TokenUrl?: string;
-    oauth2ClientId?: string;
-    oauth2TokenEndpointAuthMethod?: string;
     /** Pass `null` to explicitly clear a previously-set alias. */
     alias?: string | null;
     /** Pass `null` to explicitly clear injection templates. */
     injectionTemplates?: CredentialInjectionTemplate[] | null;
-    hasRefreshToken?: boolean;
   },
 ): CredentialMetadata {
   const result = loadFile();
@@ -305,22 +225,6 @@ export function upsertCredentialMetadata(
       existing.allowedDomains = policy.allowedDomains;
     if (policy?.usageDescription !== undefined)
       existing.usageDescription = policy.usageDescription;
-    if (policy?.expiresAt !== undefined) {
-      if (policy.expiresAt == null) {
-        delete existing.expiresAt;
-      } else {
-        existing.expiresAt = policy.expiresAt;
-      }
-    }
-    if (policy?.grantedScopes !== undefined)
-      existing.grantedScopes = policy.grantedScopes;
-    if (policy?.oauth2TokenUrl !== undefined)
-      existing.oauth2TokenUrl = policy.oauth2TokenUrl;
-    if (policy?.oauth2ClientId !== undefined)
-      existing.oauth2ClientId = policy.oauth2ClientId;
-    if (policy?.oauth2TokenEndpointAuthMethod !== undefined)
-      existing.oauth2TokenEndpointAuthMethod =
-        policy.oauth2TokenEndpointAuthMethod;
     if (policy?.alias !== undefined) {
       if (policy.alias == null) {
         delete existing.alias;
@@ -335,8 +239,6 @@ export function upsertCredentialMetadata(
         existing.injectionTemplates = policy.injectionTemplates;
       }
     }
-    if (policy?.hasRefreshToken !== undefined)
-      existing.hasRefreshToken = policy.hasRefreshToken;
     existing.updatedAt = now;
     saveFile(data);
     return existing;
@@ -349,14 +251,8 @@ export function upsertCredentialMetadata(
     allowedTools: policy?.allowedTools ?? [],
     allowedDomains: policy?.allowedDomains ?? [],
     usageDescription: policy?.usageDescription,
-    expiresAt: policy?.expiresAt ?? undefined,
-    grantedScopes: policy?.grantedScopes,
-    oauth2TokenUrl: policy?.oauth2TokenUrl,
-    oauth2ClientId: policy?.oauth2ClientId,
-    oauth2TokenEndpointAuthMethod: policy?.oauth2TokenEndpointAuthMethod,
     alias: policy?.alias ?? undefined,
     injectionTemplates: policy?.injectionTemplates ?? undefined,
-    hasRefreshToken: policy?.hasRefreshToken,
     createdAt: now,
     updatedAt: now,
   };

package/src/tools/credentials/vault.ts

@@ -1,17 +1,22 @@
 import { getConfig } from "../../config/loader.js";
 import { orchestrateOAuthConnect } from "../../oauth/connect-orchestrator.js";
 import {
-  getProviderProfile,
+  disconnectOAuthProvider,
+  getAppByProviderAndClientId,
+  getMostRecentAppByProvider,
+  getProvider,
+} from "../../oauth/oauth-store.js";
+import {
+  getProviderBehavior,
   resolveService,
   SERVICE_ALIASES,
-} from "../../oauth/provider-profiles.js";
+} from "../../oauth/provider-behaviors.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
 import { buildAssistantEvent } from "../../runtime/assistant-event.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../runtime/assistant-scope.js";
-import { credentialKey, migrateKeys } from "../../security/credential-key.js";
-import type { TokenEndpointAuthMethod } from "../../security/oauth2.js";
+import { credentialKey } from "../../security/credential-key.js";
 import {
   deleteSecureKeyAsync,
   getSecureKey,
@@ -36,50 +41,6 @@ import { toPolicyFromInput, validatePolicyInput } from "./policy-validate.js";
 
 const log = getLogger("credential-vault");
 
-/**
- * Look up a stored OAuth secret (e.g. client_secret) for a service from the
- * secure store. Checks both the canonical and alias service names.
- */
-function findStoredOAuthSecret(
-  service: string,
-  field: string,
-): string | undefined {
-  const servicesToCheck = [service];
-  // Also check the alias if the input is the canonical name, or vice versa
-  for (const [alias, canonical] of Object.entries(SERVICE_ALIASES)) {
-    if (canonical === service) servicesToCheck.push(alias);
-    if (alias === service) servicesToCheck.push(canonical);
-  }
-  for (const svc of servicesToCheck) {
-    const value = getSecureKey(credentialKey(svc, field));
-    if (value) return value;
-  }
-  return undefined;
-}
-
-/**
- * Look up the stored OAuth client_id for a service from credential metadata.
- * Checks both the canonical and alias service names.
- */
-function findStoredOAuthClientId(service: string): string | undefined {
-  const servicesToCheck = [service];
-  for (const [alias, canonical] of Object.entries(SERVICE_ALIASES)) {
-    if (canonical === service) servicesToCheck.push(alias);
-    if (alias === service) servicesToCheck.push(canonical);
-  }
-  // Check metadata first (written by oauth2_connect after successful auth)
-  for (const svc of servicesToCheck) {
-    const meta = getCredentialMetadata(svc, "access_token");
-    if (meta?.oauth2ClientId) return meta.oauth2ClientId;
-  }
-  // Fall back to secure key store (written by credential_store prompt action)
-  for (const svc of servicesToCheck) {
-    const value = getSecureKey(credentialKey(svc, "client_id"));
-    if (value) return value;
-  }
-  return undefined;
-}
-
 class CredentialStoreTool implements Tool {
   name = "credential_store";
   description =
@@ -151,16 +112,6 @@ class CredentialStoreTool implements Tool {
             description:
               'Human-readable description of intended usage (for store/prompt actions), e.g. "GitHub login for pushing changes"',
           },
-          auth_url: {
-            type: "string",
-            description:
-              "OAuth2 authorization endpoint (only for oauth2_connect action). Auto-filled for well-known services (gmail, slack).",
-          },
-          token_url: {
-            type: "string",
-            description:
-              "OAuth2 token endpoint (only for oauth2_connect action). Auto-filled for well-known services (gmail, slack).",
-          },
           scopes: {
             type: "array",
             items: { type: "string" },
@@ -172,27 +123,11 @@ class CredentialStoreTool implements Tool {
             description:
               "OAuth2 client ID (only for oauth2_connect action). If omitted, looked up from previously stored credentials.",
           },
-          extra_params: {
-            type: "object",
-            description:
-              "Extra query params for OAuth2 auth URL (only for oauth2_connect action)",
-          },
-          userinfo_url: {
-            type: "string",
-            description:
-              "Endpoint to fetch account info after OAuth2 auth (only for oauth2_connect action)",
-          },
           client_secret: {
             type: "string",
             description:
               "OAuth2 client secret for providers that require it (e.g. Google, Slack). If omitted, looked up from previously stored credentials; if still absent, PKCE-only is used (only for oauth2_connect action)",
           },
-          token_endpoint_auth_method: {
-            type: "string",
-            enum: ["client_secret_basic", "client_secret_post"],
-            description:
-              'How to send client credentials at the token endpoint: "client_secret_post" (default, in POST body) or "client_secret_basic" (HTTP Basic Auth header). Only for oauth2_connect action.',
-          },
           alias: {
             type: "string",
             description:
@@ -243,7 +178,6 @@ class CredentialStoreTool implements Tool {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    migrateKeys();
     const action = input.action as string;
 
     switch (action) {
@@ -517,6 +451,21 @@ class CredentialStoreTool implements Tool {
             "metadata delete failed after removing credential",
           );
         }
+        // Also clean up any OAuth connection for this service (best-effort)
+        try {
+          const oauthResult = await disconnectOAuthProvider(service);
+          if (oauthResult === "error") {
+            log.warn(
+              { service },
+              "OAuth disconnect failed after removing credential — secure key deletion error",
+            );
+          }
+        } catch (err) {
+          log.warn(
+            { service, err },
+            "OAuth disconnect failed after removing credential",
+          );
+        }
         return {
           content: `Deleted credential for ${service}/${field}.`,
           isError: false,
@@ -777,51 +726,42 @@ class CredentialStoreTool implements Tool {
         // Resolve aliases (e.g. "gmail" → "integration:gmail")
         const service = resolveService(rawService);
 
-        // Fill missing params from provider profile
-        const profile = getProviderProfile(service);
-
-        // Look up client_id from metadata and client_secret from secure store
-        const clientId =
-          (input.client_id as string | undefined) ??
-          findStoredOAuthClientId(service);
-        const clientSecret =
-          (input.client_secret as string | undefined) ??
-          findStoredOAuthSecret(service, "client_secret");
+        // Code-side behavioral fields (identityVerifier, setup, etc.)
+        const behavior = getProviderBehavior(service);
+        // Protocol-level config from the DB (authUrl, tokenUrl, scopes, etc.)
+        const providerRow = getProvider(service);
+
+        // Resolve client_id and client_secret.
+        // Priority:
+        //   1. Explicit input from the caller
+        //   2. oauth-store DB — when clientId is already known, look up the
+        //      matching app so the secret comes from the same app. Only fall
+        //      back to the most-recent-app heuristic when clientId is unknown.
+        let clientId = input.client_id as string | undefined;
+        let clientSecret = input.client_secret as string | undefined;
+
+        if (!clientId || !clientSecret) {
+          const dbApp = clientId
+            ? getAppByProviderAndClientId(service, clientId)
+            : getMostRecentAppByProvider(service);
+          if (dbApp) {
+            if (!clientId) clientId = dbApp.clientId;
+            if (!clientSecret) {
+              clientSecret = getSecureKey(dbApp.clientSecretCredentialPath);
+            }
+          }
+        }
 
         // Early guardrails that stay in vault.ts (credential resolution is vault-specific)
         const inputScopes = input.scopes as string[] | undefined;
 
-        if (profile) {
-          // Profile-based provider (well-known like gmail, slack, twitter):
-          // Don't pass authUrl/tokenUrl — the orchestrator resolves those from the profile.
-          // Pass user-provided scopes as requestedScopes so the scope policy engine is invoked.
-          // If no scopes provided, pass neither — let the orchestrator use profile defaults via scope policy.
-        } else {
-          // Custom/unknown provider: require authUrl, tokenUrl, scopes from input
-          if (!input.auth_url)
-            return {
-              content:
-                "Error: auth_url is required for oauth2_connect action (no well-known config for this service)",
-              isError: true,
-            };
-          if (!input.token_url)
-            return {
-              content:
-                "Error: token_url is required for oauth2_connect action (no well-known config for this service)",
-              isError: true,
-            };
-          if (!inputScopes)
-            return {
-              content:
-                "Error: scopes is required for oauth2_connect action (no well-known config for this service)",
-              isError: true,
-            };
+        if (!providerRow) {
+          return {
+            content: `Error: no OAuth provider registered for "${service}". Ensure the provider is seeded in the database.`,
+            isError: true,
+          };
         }
 
-        const authUrl =
-          (input.auth_url as string | undefined) ?? profile?.authUrl;
-        const tokenUrl =
-          (input.token_url as string | undefined) ?? profile?.tokenUrl;
         if (!clientId)
           return {
             content:
@@ -833,10 +773,10 @@ class CredentialStoreTool implements Tool {
         // agent to collect it from the user rather than letting it improvise
         // browser-automation workarounds that inevitably fail.
         const requiresSecret =
-          profile?.setup?.requiresClientSecret ??
-          !!(profile?.tokenEndpointAuthMethod || profile?.extraParams);
+          behavior?.setup?.requiresClientSecret ??
+          !!(providerRow.tokenEndpointAuthMethod || providerRow.extraParams);
         if (requiresSecret && !clientSecret) {
-          const skillId = profile?.setupSkillId;
+          const skillId = behavior?.setupSkillId;
           const skillHint = skillId
             ? `\n\nLoad the "${skillId}" skill for provider-specific instructions on obtaining the client secret.`
             : '\n\nUse credential_store with action "prompt" to securely collect the client_secret from the user before calling oauth2_connect again.';
@@ -846,25 +786,8 @@ class CredentialStoreTool implements Tool {
           };
         }
 
-        try {
-          assertMetadataWritable();
-        } catch {
-          return {
-            content:
-              "Error: credential metadata file has an unrecognized version; cannot store credentials",
-            isError: true,
-          };
-        }
-
-        const tokenEndpointAuthMethod =
-          (input.token_endpoint_auth_method as
-            | TokenEndpointAuthMethod
-            | undefined) ?? profile?.tokenEndpointAuthMethod;
-
-        // Delegate to the shared orchestrator.
-        // For profile-based providers, pass user scopes as requestedScopes so the
-        // scope policy engine (resolveScopes) is invoked. For custom providers,
-        // pass scopes directly as an explicit override.
+        // Delegate to the shared orchestrator — it resolves authUrl, tokenUrl,
+        // extraParams, userinfoUrl, and tokenEndpointAuthMethod from the DB.
         const result = await orchestrateOAuthConnect({
           service: rawService,
           clientId,
@@ -872,24 +795,7 @@ class CredentialStoreTool implements Tool {
           isInteractive: !!context.isInteractive,
           sendToClient: context.sendToClient,
           allowedTools: input.allowed_tools as string[] | undefined,
-          authUrl,
-          tokenUrl,
-          ...(profile
-            ? {
-                // Profile-based: let orchestrator resolve scopes via policy engine.
-                // Only pass requestedScopes if the user explicitly provided scopes.
-                ...(inputScopes ? { requestedScopes: inputScopes } : {}),
-              }
-            : {
-                // Custom provider: explicit scopes override (bypasses policy engine)
-                scopes: inputScopes,
-              }),
-          extraParams:
-            (input.extra_params as Record<string, string> | undefined) ??
-            profile?.extraParams,
-          userinfoUrl:
-            (input.userinfo_url as string | undefined) ?? profile?.userinfoUrl,
-          tokenEndpointAuthMethod,
+          ...(inputScopes ? { requestedScopes: inputScopes } : {}),
           onDeferredComplete: (deferredResult) => {
             // Emit oauth_connect_result to all connected SSE clients so the
             // UI can update immediately when the deferred browser flow completes.
@@ -958,8 +864,8 @@ class CredentialStoreTool implements Tool {
           };
         }
         const resolvedService = resolveService(rawService);
-        const profile = getProviderProfile(resolvedService);
-        if (!profile) {
+        const descProviderRow = getProvider(resolvedService);
+        if (!descProviderRow) {
           return {
             content: `No well-known OAuth config found for "${rawService}". Available services: ${Object.keys(
               SERVICE_ALIASES,
@@ -968,11 +874,17 @@ class CredentialStoreTool implements Tool {
           };
         }
 
+        const descBehavior = getProviderBehavior(resolvedService);
+
         // Compute the redirect URI based on callback transport
         let redirectUri: string;
-        const transport = profile.callbackTransport ?? "gateway";
-        if (transport === "loopback" && profile.loopbackPort) {
-          redirectUri = `http://127.0.0.1:${profile.loopbackPort}/oauth/callback`;
+        const transport =
+          (descProviderRow.callbackTransport as
+            | "loopback"
+            | "gateway"
+            | null) ?? "gateway";
+        if (transport === "loopback" && descProviderRow.loopbackPort) {
+          redirectUri = `http://127.0.0.1:${descProviderRow.loopbackPort}/oauth/callback`;
         } else if (transport === "loopback") {
           redirectUri =
             "(automatic — no redirect URI needed, uses random localhost port)";
@@ -986,26 +898,39 @@ class CredentialStoreTool implements Tool {
             redirectUri = `${baseUrl}/webhooks/oauth/callback`;
           } catch {
             redirectUri =
-              "(requires INGRESS_PUBLIC_BASE_URL — not currently configured)";
+              "(requires ingress.publicBaseUrl — not currently configured)";
           }
         }
 
         // Prefer explicit setup metadata, fall back to heuristic
         const requiresClientSecret =
-          profile.setup?.requiresClientSecret ??
-          !!(profile.tokenEndpointAuthMethod || profile.extraParams);
+          descBehavior?.setup?.requiresClientSecret ??
+          !!(
+            descProviderRow.tokenEndpointAuthMethod ||
+            descProviderRow.extraParams
+          );
+
+        const descDefaultScopes: string[] = descProviderRow.defaultScopes
+          ? JSON.parse(descProviderRow.defaultScopes)
+          : [];
 
         const info: Record<string, unknown> = {
           service: resolvedService,
-          authUrl: profile.authUrl,
-          tokenUrl: profile.tokenUrl,
-          scopes: profile.defaultScopes,
+          authUrl: descProviderRow.authUrl,
+          tokenUrl: descProviderRow.tokenUrl,
+          scopes: descDefaultScopes,
           callbackTransport: transport,
           redirectUri,
           requiresClientSecret,
         };
-        if (profile.setup) info.setup = profile.setup;
-        if (profile.extraParams) info.extraParams = profile.extraParams;
+        if (descBehavior?.setup) info.setup = descBehavior.setup;
+        if (descProviderRow.extraParams) {
+          try {
+            info.extraParams = JSON.parse(descProviderRow.extraParams);
+          } catch {
+            // Non-fatal
+          }
+        }
 
         return { content: JSON.stringify(info, null, 2), isError: false };
       }

package/src/tools/memory/definitions.ts

@@ -3,7 +3,7 @@ import type { ToolDefinition } from "../../providers/types.js";
 export const memoryRecallDefinition: ToolDefinition = {
   name: "memory_recall",
   description:
-    "Deep search across all memory sources (semantic, lexical, entity graph, recency) for specific information. Use this when you need to recall details about past conversations, decisions, preferences, project context, or any prior knowledge. Returns formatted memory context with item IDs for use with memory_manage.",
+    "Hybrid search across memory (semantic and recency) for specific information. Use this when you need to recall details about past conversations, decisions, preferences, project context, or any prior knowledge. Returns formatted memory context with item IDs for use with memory_manage.",
   input_schema: {
     type: "object",
     properties: {
@@ -11,10 +11,6 @@ export const memoryRecallDefinition: ToolDefinition = {
         type: "string",
         description: "The search query — be specific and descriptive",
       },
-      max_results: {
-        type: "number",
-        description: "Maximum number of memory items to return (default: 10)",
-      },
       scope: {
         type: "string",
         enum: ["default", "conversation"],
@@ -44,17 +40,12 @@ const memoryManageProperties = {
   kind: {
     type: "string" as const,
     enum: [
+      "identity",
       "preference",
-      "fact",
+      "project",
       "decision",
-      "profile",
-      "relationship",
+      "constraint",
       "event",
-      "opinion",
-      "instruction",
-      "style",
-      "playbook",
-      "learning",
     ],
     description: "Category of the memory item (required for save)",
   },