@persistio/openclaw-plugin 0.1.8 → 0.2.0

package/src/client.ts

@@ -1,61 +1,43 @@
-import type { PersistioIngestPolicy } from './ingest-policy.js';
-
-export interface PersistioConfig {
-  baseURL: string;
-  apiKey: string;
-  tokenBudget: number;
-  recallTopK: number;
-  recallMinSimilarity?: number;
-  recallTimeout: number;
-  recallIncludePending: boolean;
-  includeRelatedMemories: boolean;
-  ingest: PersistioIngestPolicy;
-  send: PersistioSendConfig;
-}
-
-export type PersistioSendRoleStatus = 'enabled' | 'disabled';
-
-export interface PersistioSendConfig {
-  roles: {
-    user: PersistioSendRoleStatus;
-    agent: PersistioSendRoleStatus;
-    tool: PersistioSendRoleStatus;
-  };
-}
+import type { PersistioV2Config } from './config.js';
 
 export interface PersistioMemory {
   id: string;
   data: string;
   subject: string;
   similarity?: number;
-  categories: string[];
-  confidence: number;
-}
-
-export interface GetMemoryOptions {
-  includePending?: boolean;
+  confidence?: number;
+  categories?: string[];
+  source?: string;
+  edge_type?: string | null;
 }
 
 export interface RecallBundle {
   global_user_rules?: string[];
-  user_rules: string[];
-  user_preferences: string[];
-  task_patterns: string[];
-  workflows: string[];
-  project: string[];
-  constraints: string[];
-  decisions: string[];
-  system_facts: string[];
-  domain_knowledge: string[];
+  user_rules?: string[];
+  user_preferences?: string[];
+  task_patterns?: string[];
+  workflows?: string[];
+  project?: string[];
+  constraints?: string[];
+  decisions?: string[];
+  system_facts?: string[];
+  domain_knowledge?: string[];
 }
 
 export interface RecallBundleResponse {
-  bundle: RecallBundle;
+  bundle?: RecallBundle;
   related_bundle?: RecallBundle;
 }
 
-export interface RecallBundleOptions {
-  includeRelated?: boolean;
+export interface RecallResult {
+  memories: PersistioMemory[];
+  relatedMemories: PersistioMemory[];
+}
+
+export interface IngestChunk {
+  role: string;
+  content: string;
+  timestamp: string;
 }
 
 export class PersistioTimeoutError extends Error {
@@ -68,83 +50,49 @@ export class PersistioTimeoutError extends Error {
 export class PersistioClient {
   private readonly baseURL: string;
   private readonly apiKey: string;
-  private readonly recallTopK: number;
-  private readonly recallMinSimilarity?: number;
-  private readonly recallTimeout: number;
-  private readonly recallIncludePending: boolean;
-  private readonly includeRelatedMemories: boolean;
-  private readonly ingestTimeout: number;
-  private readonly writeTimeout: number;
-
-  constructor(config: PersistioConfig) {
+
+  constructor(private readonly config: PersistioV2Config) {
     this.baseURL = config.baseURL.replace(/\/$/, '');
     this.apiKey = config.apiKey;
-    this.recallTopK = config.recallTopK;
-    this.recallMinSimilarity = config.recallMinSimilarity;
-    this.recallTimeout = config.recallTimeout;
-    this.recallIncludePending = config.recallIncludePending;
-    this.includeRelatedMemories = config.includeRelatedMemories;
-    this.ingestTimeout = config.ingest.timeoutMs;
-    this.writeTimeout = config.ingest.timeoutMs;
-  }
-
-  private headers(): Record<string, string> {
-    return {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${this.apiKey}`,
-    };
   }
 
-  async recall(query: string): Promise<PersistioMemory[]> {
-    return withRequestDeadline('recall', this.recallTimeout, async (signal) => {
-      const body: Record<string, unknown> = {
-        query,
-        top_k: this.recallTopK,
-        include_pending: this.recallIncludePending
-      };
-      if (typeof this.recallMinSimilarity === 'number') {
-        body.min_similarity = this.recallMinSimilarity;
-      }
-
+  async recall(query: string, options: { maxResults?: number } = {}): Promise<RecallResult> {
+    return withRequestDeadline('recall', this.config.recall.timeoutMs, async (signal) => {
+      const body = this.buildRecallBody(query, options.maxResults);
       const res = await fetch(`${this.baseURL}/v1/recall`, {
         method: 'POST',
         headers: this.headers(),
         body: JSON.stringify(body),
         signal,
       });
-      if (!res.ok) throw new Error(`Persistio recall failed: ${res.status}`);
-      const data = await res.json() as { memories: PersistioMemory[] };
-      return data.memories ?? [];
+      if (!res.ok) throw new Error(await formatHttpError('recall', res));
+      const data = await res.json() as { memories?: PersistioMemory[]; related_memories?: PersistioMemory[] };
+      return {
+        memories: Array.isArray(data.memories) ? data.memories : [],
+        relatedMemories: Array.isArray(data.related_memories) ? data.related_memories : [],
+      };
     });
   }
 
-  async recallBundle(query: string, topK?: number, options: RecallBundleOptions = {}): Promise<RecallBundleResponse> {
-    return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
-      const body: Record<string, unknown> = {
-        query,
-        top_k: topK ?? this.recallTopK,
-        include_pending: this.recallIncludePending,
-        include_related: options.includeRelated ?? this.includeRelatedMemories
+  async recallBundle(query: string): Promise<RecallBundleResponse> {
+    return withRequestDeadline('recallBundle', this.config.recall.timeoutMs, async (signal) => {
+      const body = {
+        ...this.buildRecallBody(query, this.config.recall.maxResults),
       };
-      if (typeof this.recallMinSimilarity === 'number') {
-        body.min_similarity = this.recallMinSimilarity;
-      }
-
       const res = await fetch(`${this.baseURL}/v1/recall?format=bundle`, {
         method: 'POST',
         headers: this.headers(),
         body: JSON.stringify(body),
         signal,
       });
-      if (!res.ok) throw new Error(`Persistio recallBundle failed: ${res.status}`);
-      const data = await res.json() as RecallBundleResponse;
-      return data;
+      if (!res.ok) throw new Error(await formatHttpError('recallBundle', res));
+      return await res.json() as RecallBundleResponse;
     });
   }
 
-  async ingest(sessionId: string, chunks: Array<{ role: string; content: string; timestamp: string }>): Promise<void> {
+  async ingest(sessionId: string, chunks: IngestChunk[]): Promise<void> {
     if (chunks.length === 0) return;
-    await withRequestDeadline('ingest', this.ingestTimeout, async (signal) => {
+    await withRequestDeadline('ingest', this.config.capture.timeoutMs, async (signal) => {
       const res = await fetch(`${this.baseURL}/v1/ingest`, {
         method: 'POST',
         headers: this.headers(),
@@ -155,56 +103,52 @@ export class PersistioClient {
     });
   }
 
-  async addMemory(data: string, subject: string): Promise<void> {
-    await withRequestDeadline('addMemory', this.writeTimeout, async (signal) => {
+  async storeMemory(data: string, subject: string): Promise<PersistioMemory> {
+    return withRequestDeadline('memory_store', this.config.capture.timeoutMs, async (signal) => {
       const res = await fetch(`${this.baseURL}/v1/memories`, {
         method: 'POST',
         headers: this.headers(),
         body: JSON.stringify({ data, subject }),
         signal,
       });
-      if (!res.ok) throw new Error(`Persistio addMemory failed: ${res.status}`);
+      if (!res.ok) throw new Error(await formatHttpError('memory_store', res));
+      return await res.json() as PersistioMemory;
     });
   }
 
-  async deleteMemory(id: string): Promise<void> {
-    await withRequestDeadline('deleteMemory', this.writeTimeout, async (signal) => {
-      const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
+  async forgetMemory(id: string): Promise<void> {
+    await withRequestDeadline('memory_forget', this.config.capture.timeoutMs, async (signal) => {
+      const res = await fetch(`${this.baseURL}/v1/memories/${encodeURIComponent(id)}`, {
         method: 'DELETE',
         headers: this.headers(),
         signal,
       });
-      if (!res.ok) throw new Error(`Persistio deleteMemory failed: ${res.status}`);
+      if (!res.ok) throw new Error(await formatHttpError('memory_forget', res));
     });
   }
 
-  async getMemory(id: string, options: GetMemoryOptions = {}): Promise<PersistioMemory | null> {
-    return withRequestDeadline('getMemory', this.recallTimeout, async (signal) => {
-      const query = options.includePending ? '?include_pending=true' : '';
-      const res = await fetch(`${this.baseURL}/v1/memories/${id}${query}`, {
-        headers: this.headers(),
-        signal,
-      });
-      if (res.status === 404) return null;
-      if (!res.ok) throw new Error(`Persistio getMemory failed: ${res.status}`);
-      return await res.json() as PersistioMemory;
-    });
+  private buildRecallBody(query: string, maxResults = this.config.recall.maxResults): Record<string, unknown> {
+    const body: Record<string, unknown> = {
+      query,
+      top_k: maxResults,
+      include_pending: this.config.recall.includePending,
+      include_related: this.config.recall.includeRelated,
+    };
+    if (typeof this.config.recall.minSimilarity === 'number') {
+      body.min_similarity = this.config.recall.minSimilarity;
+    }
+    return body;
   }
 
-  async listMemories(): Promise<PersistioMemory[]> {
-    return withRequestDeadline('listMemories', this.recallTimeout, async (signal) => {
-      const res = await fetch(`${this.baseURL}/v1/memories`, {
-        headers: this.headers(),
-        signal,
-      });
-      if (!res.ok) throw new Error(`Persistio listMemories failed: ${res.status}`);
-      const data = await res.json() as { items: PersistioMemory[] };
-      return data.items ?? [];
-    });
+  private headers(): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+    };
   }
 }
 
-async function withRequestDeadline<T>(
+export async function withRequestDeadline<T>(
   operation: string,
   timeoutMs: number,
   run: (signal: AbortSignal) => Promise<T>,
@@ -215,7 +159,6 @@ async function withRequestDeadline<T>(
 
   const controller = new AbortController();
   let timeout: ReturnType<typeof setTimeout> | undefined;
-
   const deadline = new Promise<never>((_resolve, reject) => {
     timeout = setTimeout(() => {
       controller.abort();
@@ -236,8 +179,7 @@ async function withRequestDeadline<T>(
 }
 
 function isAbortLikeError(err: unknown): boolean {
-  if (!(err instanceof Error)) return false;
-  return err.name === 'AbortError' || err.name === 'TimeoutError';
+  return err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError');
 }
 
 async function formatHttpError(operation: string, res: Response): Promise<string> {
@@ -245,7 +187,7 @@ async function formatHttpError(operation: string, res: Response): Promise<string
   try {
     detail = (await res.text()).trim().slice(0, 500);
   } catch {
-    // Ignore response body read failures; the status is still actionable.
+    // Status code is still useful if the body cannot be read.
   }
 
   return detail

package/src/config.ts

@@ -0,0 +1,125 @@
+export type PersistioCaptureRoleStatus = 'enabled' | 'bounded' | 'disabled';
+
+export interface PersistioV2Config {
+  baseURL: string;
+  apiKey: string;
+  autoRecall: boolean;
+  autoCapture: boolean;
+  recall: {
+    timeoutMs: number;
+    maxResults: number;
+    tokenBudget: number;
+    minSimilarity?: number;
+    includePending: boolean;
+    includeRelated: boolean;
+    queryMaxChars: number;
+  };
+  capture: {
+    timeoutMs: number;
+    maxCharsPerTurn: number;
+    maxCharsPerMessage: number;
+    maxChunksPerTurn: number;
+    maxChunkChars: number;
+    roles: {
+      user: 'enabled' | 'disabled';
+      assistant: PersistioCaptureRoleStatus;
+      tool: 'enabled' | 'disabled';
+    };
+  };
+}
+
+const DEFAULT_CONFIG: PersistioV2Config = {
+  baseURL: '',
+  apiKey: '',
+  autoRecall: true,
+  autoCapture: true,
+  recall: {
+    timeoutMs: 1200,
+    maxResults: 4,
+    tokenBudget: 400,
+    includePending: false,
+    includeRelated: false,
+    queryMaxChars: 1200,
+  },
+  capture: {
+    timeoutMs: 10000,
+    maxCharsPerTurn: 6000,
+    maxCharsPerMessage: 3000,
+    maxChunksPerTurn: 4,
+    maxChunkChars: 2000,
+    roles: {
+      user: 'enabled',
+      assistant: 'bounded',
+      tool: 'disabled',
+    },
+  },
+};
+
+function readObject(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function readString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function readBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function readPositiveInteger(value: unknown, fallback: number, min = 1): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= min
+    ? Math.floor(value)
+    : fallback;
+}
+
+function readSimilarity(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1
+    ? value
+    : undefined;
+}
+
+function readEnabledDisabled(value: unknown, fallback: 'enabled' | 'disabled'): 'enabled' | 'disabled' {
+  return value === 'enabled' || value === 'disabled' ? value : fallback;
+}
+
+function readAssistantRole(value: unknown, fallback: PersistioCaptureRoleStatus): PersistioCaptureRoleStatus {
+  return value === 'enabled' || value === 'bounded' || value === 'disabled' ? value : fallback;
+}
+
+export function resolveConfig(raw: unknown): PersistioV2Config {
+  const input = readObject(raw);
+  const recall = readObject(input['recall']);
+  const capture = readObject(input['capture']);
+  const roles = readObject(capture['roles']);
+
+  return {
+    baseURL: readString(input['baseURL'], DEFAULT_CONFIG.baseURL),
+    apiKey: readString(input['apiKey'], DEFAULT_CONFIG.apiKey),
+    autoRecall: readBoolean(input['autoRecall'], DEFAULT_CONFIG.autoRecall),
+    autoCapture: readBoolean(input['autoCapture'], DEFAULT_CONFIG.autoCapture),
+    recall: {
+      timeoutMs: readPositiveInteger(recall['timeoutMs'], DEFAULT_CONFIG.recall.timeoutMs),
+      maxResults: readPositiveInteger(recall['maxResults'], DEFAULT_CONFIG.recall.maxResults),
+      tokenBudget: readPositiveInteger(recall['tokenBudget'], DEFAULT_CONFIG.recall.tokenBudget),
+      minSimilarity: readSimilarity(recall['minSimilarity']),
+      includePending: readBoolean(recall['includePending'], DEFAULT_CONFIG.recall.includePending),
+      includeRelated: readBoolean(recall['includeRelated'], DEFAULT_CONFIG.recall.includeRelated),
+      queryMaxChars: readPositiveInteger(recall['queryMaxChars'], DEFAULT_CONFIG.recall.queryMaxChars, 100),
+    },
+    capture: {
+      timeoutMs: readPositiveInteger(capture['timeoutMs'], DEFAULT_CONFIG.capture.timeoutMs),
+      maxCharsPerTurn: readPositiveInteger(capture['maxCharsPerTurn'], DEFAULT_CONFIG.capture.maxCharsPerTurn),
+      maxCharsPerMessage: readPositiveInteger(capture['maxCharsPerMessage'], DEFAULT_CONFIG.capture.maxCharsPerMessage),
+      maxChunksPerTurn: readPositiveInteger(capture['maxChunksPerTurn'], DEFAULT_CONFIG.capture.maxChunksPerTurn),
+      maxChunkChars: readPositiveInteger(capture['maxChunkChars'], DEFAULT_CONFIG.capture.maxChunkChars, 256),
+      roles: {
+        user: readEnabledDisabled(roles['user'], DEFAULT_CONFIG.capture.roles.user),
+        assistant: readAssistantRole(roles['assistant'], DEFAULT_CONFIG.capture.roles.assistant),
+        tool: readEnabledDisabled(roles['tool'], DEFAULT_CONFIG.capture.roles.tool),
+      },
+    },
+  };
+}