loom-claw 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,38 @@
+{
+  "id": "loom-claw",
+  "kind": "context-engine",
+  "uiHints": {
+    "loomBaseUrl": {
+      "label": "Loom Backend URL",
+      "help": "URL of the running Loom FastAPI server (default: http://localhost:8666)"
+    },
+    "sessionId": {
+      "label": "Loom Session ID",
+      "help": "Session ID to use on the Loom backend (default: 'default')"
+    },
+    "schemaId": {
+      "label": "Schema ID",
+      "help": "Shared schema file ID for cross-session memory (default: 'default')"
+    },
+    "schemaTemplate": {
+      "label": "Schema Template",
+      "help": "Initial schema template to apply: 'user_profile', 'general', or 'roleplay'"
+    },
+    "buildEveryNTurns": {
+      "label": "Build Every N Turns",
+      "help": "Run schema extraction every N conversation turns (default: 1)"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "loomBaseUrl": { "type": "string" },
+      "sessionId": { "type": "string" },
+      "schemaId": { "type": "string" },
+      "schemaTemplate": { "type": "string" },
+      "buildEveryNTurns": { "type": "integer", "minimum": 1 }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "loom-claw",
+  "version": "0.1.0",
+  "description": "Loom cognitive memory system as an OpenClaw Context Engine plugin — connects to a Loom Python backend for structured schema-based long-term memory",
+  "type": "module",
+  "main": "index.ts",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "context-engine",
+    "loom",
+    "cognitive-memory",
+    "long-term-memory",
+    "schema-memory",
+    "llm"
+  ],
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run --dir test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.7",
+      "minGatewayVersion": "2026.4.7"
+    },
+    "build": {
+      "openclawVersion": "2026.4.7",
+      "pluginSdkVersion": "2026.4.7"
+    }
+  }
+}

package/src/client.ts

@@ -0,0 +1,245 @@
+/**
+ * Loom API client — thin HTTP wrapper around the Loom FastAPI backend.
+ *
+ * All core cognitive memory logic stays in the Python backend.
+ * This client simply calls the right endpoints and returns typed results.
+ */
+
+import type {
+  BuildResponse,
+  RecallAllResponse,
+  RecallResponse,
+  InspectAllResponse,
+  SchemaInfo,
+  SchemaFileDataResponse,
+} from "./types.js";
+
+export class LoomClient {
+  private baseUrl: string;
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+  }
+
+  async build(
+    text: string,
+    sessionId: string,
+    sourceSessionId = "",
+  ): Promise<BuildResponse> {
+    const body: Record<string, string> = { text, session_id: sessionId };
+    if (sourceSessionId) body.source_session_id = sourceSessionId;
+    return this._post<BuildResponse>("/api/build", body);
+  }
+
+  async recallAll(schemaId: string): Promise<RecallAllResponse> {
+    const params = schemaId ? `?schema_id=${encodeURIComponent(schemaId)}` : "";
+    return this._get<RecallAllResponse>(`/api/schemas/recall-all${params}`);
+  }
+
+  async recall(message: string, sessionId: string, schemaId?: string): Promise<RecallResponse> {
+    return this._post<RecallResponse>("/api/schemas/recall", {
+      message,
+      session_id: sessionId,
+      schema_id: schemaId || "",
+    });
+  }
+
+  async inspectAll(
+    schemaId: string,
+    showValues = true,
+    maxDepth = -1,
+  ): Promise<InspectAllResponse> {
+    const qs = new URLSearchParams();
+    if (schemaId) qs.set("schema_id", schemaId);
+    qs.set("show_values", String(showValues));
+    qs.set("max_depth", String(maxDepth));
+    return this._get<InspectAllResponse>(`/api/schemas/inspect-all?${qs}`);
+  }
+
+  async listSchemas(): Promise<string[]> {
+    return this._get<string[]>("/api/schemas");
+  }
+
+  async getSchema(name: string): Promise<SchemaInfo> {
+    return this._get<SchemaInfo>(`/api/schemas/${encodeURIComponent(name)}`);
+  }
+
+  async deleteSchema(name: string, schemaId = ""): Promise<{ status: string; message: string }> {
+    const qs = schemaId ? `?schema_id=${encodeURIComponent(schemaId)}` : "";
+    return this._delete(`/api/schemas/${encodeURIComponent(name)}${qs}`);
+  }
+
+  async clearAllSchemas(schemaId = ""): Promise<{ status: string; message: string; count: number }> {
+    const qs = schemaId ? `?schema_id=${encodeURIComponent(schemaId)}` : "";
+    return this._delete(`/api/schemas${qs}`);
+  }
+
+  async createSchema(
+    name: string,
+    fields?: Record<string, { value: string; description: string }>,
+  ): Promise<SchemaInfo> {
+    return this._post<SchemaInfo>("/api/schemas", { name, fields });
+  }
+
+  async getSchemaFileData(schemaId: string): Promise<SchemaFileDataResponse> {
+    return this._get<SchemaFileDataResponse>(
+      `/api/schemas/file-data/${encodeURIComponent(schemaId)}`,
+    );
+  }
+
+  async createSchemaFromTemplate(
+    templateName: string,
+    customFields?: Record<string, { value: string; description: string }>,
+  ): Promise<SchemaInfo> {
+    return this._post<SchemaInfo>("/api/schemas/from-template", {
+      template_name: templateName,
+      custom_fields: customFields,
+    });
+  }
+
+  async listTemplates(): Promise<Array<{ name: string; description: string }>> {
+    return this._get("/api/templates");
+  }
+
+  async listTemplatesGrouped(): Promise<Record<string, Array<{ name: string; description: string; source: string; domains: string[]; domain_count: number }>>> {
+    return this._get("/api/templates/grouped");
+  }
+
+  async getTemplate(name: string): Promise<{
+    name: string;
+    description: string;
+    source: string;
+    domains: string[];
+    data: Record<string, unknown>;
+  }> {
+    return this._get(`/api/templates/${encodeURIComponent(name)}`);
+  }
+
+  async saveCustomTemplate(data: Record<string, unknown>): Promise<{ status: string; path: string; name: string }> {
+    return this._post("/api/templates/custom", data);
+  }
+
+  async deleteCustomTemplate(name: string): Promise<{ status: string; name: string }> {
+    return this._delete(`/api/templates/custom/${encodeURIComponent(name)}`);
+  }
+
+  async createSession(
+    sessionId: string,
+    schemaId = "default",
+    sourceSessionId = "",
+  ): Promise<{ status: string; session_id: string; schema_id: string }> {
+    const qs = new URLSearchParams({ session_id: sessionId, schema_id: schemaId });
+    if (sourceSessionId) qs.set("source_session_id", sourceSessionId);
+    return this._post(`/api/sessions?${qs}`, undefined);
+  }
+
+  async switchSchema(
+    sessionId: string,
+    targetSchemaId: string,
+    sourceSessionId = "",
+  ): Promise<{ status: string; session_id: string; schema_id: string; message?: string }> {
+    const body: Record<string, string> = {
+      session_id: sessionId,
+      target_schema_id: targetSchemaId,
+    };
+    if (sourceSessionId) body.source_session_id = sourceSessionId;
+    return this._post("/api/schemas/switch", body);
+  }
+
+  async listSessions(): Promise<Array<{ session_id: string; schema_id: string; file_size: number; chat_rounds: number; schema_count: number }>> {
+    return this._get("/api/sessions");
+  }
+
+  async updateSchemaFromChat(
+    sessionId: string,
+    rounds?: number,
+  ): Promise<{ status: string; message: string }> {
+    return this._post("/api/update-schema-from-chat", {
+      session_id: sessionId,
+      rounds,
+    });
+  }
+
+  async newSchema(sessionId: string): Promise<{ status: string; backup_id?: string }> {
+    return this._post("/api/schemas/new", { session_id: sessionId });
+  }
+
+  async createSchemaFile(
+    sessionId: string,
+    schemaId = "",
+    template = "",
+  ): Promise<{ status: string; schema_id: string; template?: string }> {
+    return this._post("/api/schemas/create-file", {
+      schema_id: schemaId,
+      session_id: sessionId,
+      template,
+    });
+  }
+
+  async listSavedSchemas(): Promise<Array<{ schema_id: string; file_size: number; domain_count: number }>> {
+    return this._get("/api/schemas/saved");
+  }
+
+  async listBackups(schemaId = ""): Promise<Array<{ backup_id: string; file_size: number; created_at: string }>> {
+    const qs = schemaId ? `?schema_id=${encodeURIComponent(schemaId)}` : "";
+    return this._get(`/api/schemas/backups${qs}`);
+  }
+
+  async restoreSchema(backupId: string, targetSchemaId = ""): Promise<{ status: string; backup_id: string }> {
+    return this._post("/api/schemas/restore", {
+      backup_id: backupId,
+      target_schema_id: targetSchemaId,
+    });
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      const resp = await fetch(`${this.baseUrl}/api/schemas`, {
+        method: "GET",
+        signal: AbortSignal.timeout(5000),
+      });
+      return resp.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  // -- Internal helpers --
+
+  private async _get<T>(path: string): Promise<T> {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" },
+    });
+    if (!resp.ok) {
+      const detail = await resp.text().catch(() => resp.statusText);
+      throw new Error(`Loom API error ${resp.status} on GET ${path}: ${detail}`);
+    }
+    return (await resp.json()) as T;
+  }
+
+  private async _post<T>(path: string, body: unknown): Promise<T> {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!resp.ok) {
+      const detail = await resp.text().catch(() => resp.statusText);
+      throw new Error(`Loom API error ${resp.status} on POST ${path}: ${detail}`);
+    }
+    return (await resp.json()) as T;
+  }
+
+  private async _delete<T = Record<string, unknown>>(path: string): Promise<T> {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+    });
+    if (!resp.ok) {
+      const detail = await resp.text().catch(() => resp.statusText);
+      throw new Error(`Loom API error ${resp.status} on DELETE ${path}: ${detail}`);
+    }
+    return (await resp.json()) as T;
+  }
+}

package/src/config.ts

@@ -0,0 +1,53 @@
+/**
+ * Plugin configuration resolution.
+ * Merges environment variables with plugin config values.
+ */
+
+import type { LoomPluginConfig } from "./types.js";
+
+export function resolveConfig(
+  env: NodeJS.ProcessEnv,
+  raw: Record<string, unknown>,
+): LoomPluginConfig {
+  return {
+    enabled: bool(raw.enabled, env.LOOM_ENABLED, true),
+    loomBaseUrl: str(
+      raw.loomBaseUrl,
+      env.LOOM_BASE_URL,
+      "http://localhost:8666",
+    ),
+    sessionId: str(raw.sessionId, env.LOOM_SESSION_ID, "default"),
+    schemaId: str(raw.schemaId, env.LOOM_SCHEMA_ID, "default"),
+    schemaTemplate: str(raw.schemaTemplate, env.LOOM_SCHEMA_TEMPLATE, ""),
+    buildEveryNTurns: num(raw.buildEveryNTurns, env.LOOM_BUILD_EVERY_N_TURNS, 1),
+  };
+}
+
+function str(...sources: Array<unknown>): string {
+  for (const s of sources) {
+    if (typeof s === "string" && s.trim()) return s.trim();
+  }
+  return "";
+}
+
+function num(...sources: Array<unknown>): number {
+  for (const s of sources) {
+    if (s !== undefined && s !== null && s !== "") {
+      const n = Number(s);
+      if (!Number.isNaN(n)) return Math.round(n);
+    }
+  }
+  return 0;
+}
+
+function bool(...sources: Array<unknown>): boolean {
+  for (const s of sources) {
+    if (typeof s === "boolean") return s;
+    if (typeof s === "string") {
+      const lower = s.toLowerCase();
+      if (lower === "true" || lower === "1" || lower === "yes") return true;
+      if (lower === "false" || lower === "0" || lower === "no") return false;
+    }
+  }
+  return true;
+}