Skip to content
Python
4.8 KB
Raw Blame
/**
 * Shared type definitions for the OpenClaw HY Memory plugin.
 */

/** HY Memory processing mode (maps to SDK MEMORY_MODE) */
export type MemoryMode = "lite" | "pro" | "ultra";

export const MEMORY_MODES: readonly MemoryMode[] = ["lite", "pro", "ultra"] as const;

/** LLM provider configuration */
export interface LLMProviderConfig {
  provider: string;    // "openai" | "ollama" | "anthropic"
  model: string;
  apiKey?: string;
  baseUrl?: string;
  temperature?: number;
  maxTokens?: number;
  thinkingMode?: string;  // "disabled" | "enabled" | "auto"
}

/** Embedding provider configuration */
export interface EmbedderProviderConfig {
  provider: string;    // "openai" | "ollama" | etc.
  model: string;
  apiKey?: string;
  baseUrl?: string;
  dims?: number;
  extraHeaders?: Record<string, string>;
  extraBody?: Record<string, unknown>;
}

/** Vector store configuration */
export interface VectorStoreConfig {
  provider: string;    // "chroma" | "qdrant" | "faiss"
  host?: string;
  port?: number;
  apiKey?: string;
  collectionName?: string;
  persistDirectory?: string;
}

export interface HyMemoryConfig {
  /** Base URL of the HY Memory server */
  serverUrl: string;
  /** User ID for scoping memories */
  userId: string;
  /** Agent ID (default: "default_agent") */
  agentId: string;
  /** Session ID (default: "default_session") */
  sessionId: string;
  /**
   * SDK processing mode: lite (embed only) | pro (LLM extract) | ultra (pro + System 2 + Kuzu graph).
   * ultra always uses embedded Kuzu; no external graph service.
   */
  mode: MemoryMode;
  /** Auto-recall: inject relevant memories before each agent turn */
  autoRecall: boolean;
  /** Auto-capture: store conversation context after each agent turn */
  autoCapture: boolean;
  /** Max results for search */
  topK: number;
  /** Min score threshold for search */
  searchThreshold: number;
  /** Max results for profile memories */
  profileLimit: number;
  /** Min score threshold for profile memories */
  profileMinScore: number;
  /** Python executable path */
  pythonPath: string;
  /** Whether to auto-start the Python server */
  autoStartServer: boolean;
  /** Port for the Python server */
  serverPort: number;
  /** How many agent turns between each auto-capture write (default: 5) */
  memoryWriteTurnWindow: number;
  /** Whether setup is needed (server not reachable) */
  needsSetup?: boolean;

  /** LLM provider (for memory extraction / reconciliation) */
  llm?: LLMProviderConfig;
  /** Embedding provider */
  embedder?: EmbedderProviderConfig;
  /** Vector store backend */
  vectorStore?: VectorStoreConfig;
  /** Python server log level (default: "INFO") */
  logLevel?: string;
}

export interface MemoryItem {
  memory_id: string;
  content: string;
  score?: number;
  layer?: string;
  speculate?: string | null;
  source_raw_memory_id?: string | null;
  tags?: string[];
  memory_at?: string | null;
  gmt_created?: string | null;
  user_id?: string;
  agent_id?: string;
  session_id?: string;
}

export interface AddResult {
  success: boolean;
  memory_id: string;
  request_id: string;
  elapsed_ms: number;
  error_code?: number | null;
  error_message?: string | null;
}

export interface SearchResult {
  request_id: string;
  memories: MemoryItem[];
  elapsed_ms: number;
}

export interface ListBucket {
  memories: MemoryItem[];
  total: number;
  limit: number;
  offset: number;
}

export interface GraphListBucket {
  nodes: MemoryItem[];
  total: number;
  limit: number;
  offset: number;
  isolation_key?: string;
}

export interface ListResult {
  vdb: ListBucket;
  graph?: GraphListBucket;
  elapsed_ms: number;
}

export interface DeleteResult {
  success: boolean;
  deleted_count: number;
  request_id: string;
  elapsed_ms: number;
}

export interface HyMemoryProvider {
  add(
    data: string | Array<{ role: string; content: string }>,
    options: {
      user_id: string;
      agent_id?: string;
      session_id?: string;
      enable_agent?: boolean;
      memory_at?: string;
    },
  ): Promise<AddResult>;

  addExtracted(
    contents: string | string[],
    options: {
      user_id: string;
      agent_id?: string;
      session_id?: string;
      memory_at?: string;
    },
  ): Promise<AddResult>;

  search(
    query: string,
    options: { user_id: string; user_ids?: string[]; agent_ids?: string[]; limit?: number; min_score?: number; profile_limit?: number; profile_min_score?: number },
  ): Promise<SearchResult>;

  get(memoryId: string): Promise<MemoryItem | null>;

  list(options: { user_id: string; agent_id?: string; limit?: number; offset?: number }): Promise<ListResult>;

  update(memoryId: string, content: string): Promise<AddResult>;

  delete(memoryId: string): Promise<DeleteResult>;

  deleteAll(options: { user_id: string; agent_ids?: string[]; session_ids?: string[] }): Promise<DeleteResult>;

  healthCheck(): Promise<boolean>;
}