@kodelyth/memory-lancedb 2026.5.42 → 2026.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kodelyth/memory-lancedb",
-  "version": "2026.5.42",
+  "version": "2026.6.1",
   "description": "Klaw LanceDB-backed long-term memory plugin with auto-recall/capture",
   "repository": {
     "type": "git",
@@ -34,6 +34,21 @@
     "release": {
       "publishToClawHub": true,
       "publishToNpm": true
+    },
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist/**",
+    "klaw.plugin.json"
+  ],
+  "peerDependencies": {
+    "klaw": ">=2026.5.39"
+  },
+  "peerDependenciesMeta": {
+    "klaw": {
+      "optional": true
     }
   }
 }

package/api.ts

@@ -1,2 +0,0 @@
-export { definePluginEntry, type KlawPluginApi } from "klaw/plugin-sdk/plugin-entry";
-export { resolveStateDir } from "klaw/plugin-sdk/state-paths";

package/cli-metadata.ts

@@ -1,18 +0,0 @@
-import { definePluginEntry } from "klaw/plugin-sdk/core";
-
-export default definePluginEntry({
-  id: "memory-lancedb",
-  name: "Memory LanceDB",
-  description: "LanceDB-backed memory provider",
-  register(api) {
-    api.registerCli(() => {}, {
-      descriptors: [
-        {
-          name: "ltm",
-          description: "Inspect and query LanceDB-backed memory",
-          hasSubcommands: true,
-        },
-      ],
-    });
-  },
-});

package/config.test.ts

@@ -1,178 +0,0 @@
-import fs from "node:fs";
-import { type JsonSchemaObject, validateJsonSchemaValue } from "klaw/plugin-sdk/config-schema";
-import { describe, expect, it } from "vitest";
-import { memoryConfigSchema } from "./config.js";
-
-const manifest = JSON.parse(
-  fs.readFileSync(new URL("./klaw.plugin.json", import.meta.url), "utf-8"),
-) as { configSchema: JsonSchemaObject };
-
-describe("memory-lancedb config", () => {
-  it("accepts dreaming in the manifest schema and preserves it in runtime parsing", () => {
-    const manifestResult = validateJsonSchemaValue({
-      schema: manifest.configSchema,
-      cacheKey: "memory-lancedb.manifest.dreaming",
-      value: {
-        embedding: {
-          apiKey: "sk-test",
-        },
-        dreaming: {
-          enabled: true,
-        },
-      },
-    });
-
-    const parsed = memoryConfigSchema.parse({
-      embedding: {
-        apiKey: "sk-test",
-      },
-      dreaming: {
-        enabled: true,
-      },
-    });
-
-    expect(manifestResult.ok).toBe(true);
-    expect(parsed.dreaming).toEqual({
-      enabled: true,
-    });
-  });
-
-  it("accepts provider-backed embedding config without a plugin apiKey", () => {
-    const manifestResult = validateJsonSchemaValue({
-      schema: manifest.configSchema,
-      cacheKey: "memory-lancedb.manifest.provider-auth",
-      value: {
-        embedding: {
-          provider: "openai",
-          model: "text-embedding-3-small",
-        },
-      },
-    });
-
-    const parsed = memoryConfigSchema.parse({
-      embedding: {
-        provider: "openai",
-        model: "text-embedding-3-small",
-      },
-    });
-
-    expect(manifestResult.ok).toBe(true);
-    expect(parsed.embedding.apiKey).toBeUndefined();
-    expect(parsed.embedding.provider).toBe("openai");
-  });
-
-  it("rejects empty embedding config in the manifest schema and runtime parser", () => {
-    const manifestResult = validateJsonSchemaValue({
-      schema: manifest.configSchema,
-      cacheKey: "memory-lancedb.manifest.empty-embedding",
-      value: {
-        embedding: {},
-      },
-    });
-
-    expect(manifestResult.ok).toBe(false);
-    if (!manifestResult.ok) {
-      expect(manifestResult.errors.map((error) => error.text)).toContain(
-        "embedding: must NOT have fewer than 1 properties",
-      );
-    }
-
-    expect(() => {
-      memoryConfigSchema.parse({
-        embedding: {},
-      });
-    }).toThrow("embedding config must include at least one setting");
-  });
-
-  it("allows missing embedding config in the manifest so setup can discover fields", () => {
-    const manifestResult = validateJsonSchemaValue({
-      schema: manifest.configSchema,
-      cacheKey: "memory-lancedb.manifest.missing-embedding",
-      value: {},
-    });
-
-    expect(manifestResult.ok).toBe(true);
-    expect(() => {
-      memoryConfigSchema.parse({});
-    }).toThrow("embedding config required");
-  });
-
-  it("rejects empty embedding providers", () => {
-    expect(() => {
-      memoryConfigSchema.parse({
-        embedding: {
-          provider: "",
-          model: "text-embedding-3-small",
-        },
-      });
-    }).toThrow("embedding.provider must not be empty");
-  });
-
-  it("still rejects unrelated unknown top-level config keys", () => {
-    expect(() => {
-      memoryConfigSchema.parse({
-        embedding: {
-          apiKey: "sk-test",
-        },
-        dreaming: {
-          enabled: true,
-        },
-        unexpected: true,
-      });
-    }).toThrow("memory config has unknown keys: unexpected");
-  });
-
-  it("accepts custom trigger literals in the manifest schema and runtime parser", () => {
-    const manifestResult = validateJsonSchemaValue({
-      schema: manifest.configSchema,
-      cacheKey: "memory-lancedb.manifest.custom-triggers",
-      value: {
-        embedding: {
-          apiKey: "sk-test",
-        },
-        customTriggers: ["记住", "important project"],
-      },
-    });
-
-    const parsed = memoryConfigSchema.parse({
-      embedding: {
-        apiKey: "sk-test",
-      },
-      customTriggers: ["  记住  ", "important project"],
-    });
-
-    expect(manifestResult.ok).toBe(true);
-    expect(parsed.customTriggers).toEqual(["记住", "important project"]);
-  });
-
-  it("rejects unsafe custom trigger config values", () => {
-    expect(() => {
-      memoryConfigSchema.parse({
-        embedding: {
-          apiKey: "sk-test",
-        },
-        customTriggers: ["记住", ""],
-      });
-    }).toThrow("customTriggers.1 must not be empty");
-
-    expect(() => {
-      memoryConfigSchema.parse({
-        embedding: {
-          apiKey: "sk-test",
-        },
-        customTriggers: ["x".repeat(101)],
-      });
-    }).toThrow("customTriggers.0 must be at most 100 characters");
-  });
-
-  it("rejects non-object dreaming values in runtime parsing", () => {
-    expect(() => {
-      memoryConfigSchema.parse({
-        embedding: {
-          apiKey: "sk-test",
-        },
-        dreaming: true,
-      });
-    }).toThrow("dreaming config must be an object");
-  });
-});

package/config.ts

@@ -1,283 +0,0 @@
-import fs from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-export type MemoryConfig = {
-  embedding: {
-    provider: string;
-    model: string;
-    apiKey?: string;
-    baseUrl?: string;
-    dimensions?: number;
-  };
-  dreaming?: Record<string, unknown>;
-  dbPath?: string;
-  autoCapture?: boolean;
-  autoRecall?: boolean;
-  captureMaxChars?: number;
-  customTriggers?: string[];
-  recallMaxChars?: number;
-  storageOptions?: Record<string, string>;
-};
-
-export const MEMORY_CATEGORIES = ["preference", "fact", "decision", "entity", "other"] as const;
-export type MemoryCategory = (typeof MEMORY_CATEGORIES)[number];
-
-const DEFAULT_MODEL = "text-embedding-3-small";
-export const DEFAULT_CAPTURE_MAX_CHARS = 500;
-export const DEFAULT_RECALL_MAX_CHARS = 1000;
-const LEGACY_STATE_DIRS: string[] = [];
-
-function resolveDefaultDbPath(): string {
-  const home = homedir();
-  const preferred = join(home, ".klaw", "memory", "lancedb");
-  try {
-    if (fs.existsSync(preferred)) {
-      return preferred;
-    }
-  } catch {
-    // best-effort
-  }
-
-  for (const legacy of LEGACY_STATE_DIRS) {
-    const candidate = join(home, legacy, "memory", "lancedb");
-    try {
-      if (fs.existsSync(candidate)) {
-        return candidate;
-      }
-    } catch {
-      // best-effort
-    }
-  }
-
-  return preferred;
-}
-
-const DEFAULT_DB_PATH = resolveDefaultDbPath();
-
-const EMBEDDING_DIMENSIONS: Record<string, number> = {
-  "text-embedding-3-small": 1536,
-  "text-embedding-3-large": 3072,
-};
-const EMBEDDING_CONFIG_KEYS = ["provider", "apiKey", "model", "baseUrl", "dimensions"] as const;
-
-function assertAllowedKeys(value: Record<string, unknown>, allowed: string[], label: string) {
-  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
-  if (unknown.length === 0) {
-    return;
-  }
-  throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
-}
-
-export function vectorDimsForModel(model: string): number {
-  const dims = EMBEDDING_DIMENSIONS[model];
-  if (!dims) {
-    throw new Error(`Unsupported embedding model: ${model}`);
-  }
-  return dims;
-}
-
-function resolveEnvVars(value: string): string {
-  return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
-    const envValue = process.env[envVar];
-    if (!envValue) {
-      throw new Error(`Environment variable ${envVar} is not set`);
-    }
-    return envValue;
-  });
-}
-
-function resolveEmbeddingModel(embedding: Record<string, unknown>): string {
-  const model = typeof embedding.model === "string" ? embedding.model : DEFAULT_MODEL;
-  if (typeof embedding.dimensions !== "number") {
-    vectorDimsForModel(model);
-  }
-  return model;
-}
-
-export const memoryConfigSchema = {
-  parse(value: unknown): MemoryConfig {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-      throw new Error("memory config required");
-    }
-    const cfg = value as Record<string, unknown>;
-    assertAllowedKeys(
-      cfg,
-      [
-        "embedding",
-        "dreaming",
-        "dbPath",
-        "autoCapture",
-        "autoRecall",
-        "captureMaxChars",
-        "customTriggers",
-        "recallMaxChars",
-        "storageOptions",
-      ],
-      "memory config",
-    );
-
-    const embedding = cfg.embedding as Record<string, unknown> | undefined;
-    if (!embedding || typeof embedding !== "object" || Array.isArray(embedding)) {
-      throw new Error("embedding config required");
-    }
-    assertAllowedKeys(embedding, [...EMBEDDING_CONFIG_KEYS], "embedding config");
-    if (Object.keys(embedding).length === 0) {
-      throw new Error("embedding config must include at least one setting");
-    }
-
-    const model = resolveEmbeddingModel(embedding);
-    const provider = typeof embedding.provider === "string" ? embedding.provider.trim() : "openai";
-    if (!provider) {
-      throw new Error("embedding.provider must not be empty");
-    }
-
-    const captureMaxChars =
-      typeof cfg.captureMaxChars === "number" ? Math.floor(cfg.captureMaxChars) : undefined;
-    const recallMaxChars =
-      typeof cfg.recallMaxChars === "number" ? Math.floor(cfg.recallMaxChars) : undefined;
-    if (
-      typeof captureMaxChars === "number" &&
-      (captureMaxChars < 100 || captureMaxChars > 10_000)
-    ) {
-      throw new Error("captureMaxChars must be between 100 and 10000");
-    }
-    if (typeof recallMaxChars === "number" && (recallMaxChars < 100 || recallMaxChars > 10_000)) {
-      throw new Error("recallMaxChars must be between 100 and 10000");
-    }
-    let customTriggers: string[] | undefined;
-    if (cfg.customTriggers !== undefined) {
-      if (!Array.isArray(cfg.customTriggers)) {
-        throw new Error("customTriggers must be an array of strings");
-      }
-      customTriggers = cfg.customTriggers.map((trigger, index) => {
-        if (typeof trigger !== "string") {
-          throw new Error(`customTriggers.${index} must be a string`);
-        }
-        const normalized = trigger.trim();
-        if (!normalized) {
-          throw new Error(`customTriggers.${index} must not be empty`);
-        }
-        if (normalized.length > 100) {
-          throw new Error(`customTriggers.${index} must be at most 100 characters`);
-        }
-        return normalized;
-      });
-      if (customTriggers.length > 50) {
-        throw new Error("customTriggers must include at most 50 entries");
-      }
-    }
-
-    const dreaming =
-      cfg.dreaming === undefined
-        ? undefined
-        : cfg.dreaming && typeof cfg.dreaming === "object" && !Array.isArray(cfg.dreaming)
-          ? (cfg.dreaming as Record<string, unknown>)
-          : (() => {
-              throw new Error("dreaming config must be an object");
-            })();
-
-    // Parse storageOptions (object with string values)
-    let storageOptions: Record<string, string> | undefined;
-    const storageOpts = cfg.storageOptions as Record<string, unknown> | undefined;
-    if (storageOpts !== undefined && storageOpts !== null) {
-      if (!storageOpts || typeof storageOpts !== "object" || Array.isArray(storageOpts)) {
-        throw new Error("storageOptions must be an object");
-      }
-      storageOptions = {};
-      // Validate all values are strings
-      for (const [key, value] of Object.entries(storageOpts)) {
-        if (typeof value !== "string") {
-          throw new Error(`storageOptions.${key} must be a string`);
-        }
-        storageOptions[key] = resolveEnvVars(value);
-      }
-    }
-
-    return {
-      embedding: {
-        provider,
-        model,
-        apiKey: typeof embedding.apiKey === "string" ? resolveEnvVars(embedding.apiKey) : undefined,
-        baseUrl:
-          typeof embedding.baseUrl === "string" ? resolveEnvVars(embedding.baseUrl) : undefined,
-        dimensions: typeof embedding.dimensions === "number" ? embedding.dimensions : undefined,
-      },
-      dreaming,
-      dbPath: typeof cfg.dbPath === "string" ? cfg.dbPath : DEFAULT_DB_PATH,
-      autoCapture: cfg.autoCapture === true,
-      autoRecall: cfg.autoRecall !== false,
-      captureMaxChars: captureMaxChars ?? DEFAULT_CAPTURE_MAX_CHARS,
-      ...(customTriggers ? { customTriggers } : {}),
-      recallMaxChars: recallMaxChars ?? DEFAULT_RECALL_MAX_CHARS,
-      ...(storageOptions ? { storageOptions } : {}),
-    };
-  },
-  uiHints: {
-    "embedding.provider": {
-      label: "Embedding Provider",
-      placeholder: "openai",
-      help: "Memory embedding provider adapter to use (for example openai, github-copilot, ollama)",
-    },
-    "embedding.apiKey": {
-      label: "OpenAI API Key",
-      sensitive: true,
-      placeholder: "sk-proj-...",
-      help: "Optional API key override for OpenAI-compatible embeddings; omit to use configured provider auth",
-    },
-    "embedding.baseUrl": {
-      label: "Base URL",
-      placeholder: "https://api.openai.com/v1",
-      help: "Optional provider or OpenAI-compatible embedding endpoint base URL",
-      advanced: true,
-    },
-    "embedding.dimensions": {
-      label: "Dimensions",
-      placeholder: "1536",
-      help: "Vector dimensions for custom models (required for non-standard models)",
-      advanced: true,
-    },
-    "embedding.model": {
-      label: "Embedding Model",
-      placeholder: DEFAULT_MODEL,
-      help: "OpenAI embedding model to use",
-    },
-    dbPath: {
-      label: "Database Path",
-      placeholder: "~/.klaw/memory/lancedb",
-      advanced: true,
-      help: "Local filesystem path or cloud storage URI (s3://, gs://) for LanceDB database",
-    },
-    autoCapture: {
-      label: "Auto-Capture",
-      help: "Automatically capture important information from conversations",
-    },
-    autoRecall: {
-      label: "Auto-Recall",
-      help: "Automatically inject relevant memories into context",
-    },
-    captureMaxChars: {
-      label: "Capture Max Chars",
-      help: "Maximum message length eligible for auto-capture",
-      advanced: true,
-      placeholder: String(DEFAULT_CAPTURE_MAX_CHARS),
-    },
-    customTriggers: {
-      label: "Custom Triggers",
-      help: "Literal phrases that should make auto-capture consider a message memory-worthy",
-      advanced: true,
-    },
-    recallMaxChars: {
-      label: "Recall Query Max Chars",
-      help: "Maximum prompt/query length embedded for memory recall. Lower for small local embedding models.",
-      advanced: true,
-      placeholder: String(DEFAULT_RECALL_MAX_CHARS),
-    },
-    storageOptions: {
-      label: "Storage Options",
-      sensitive: true,
-      advanced: true,
-      help: "Storage configuration options (access_key, secret_key, endpoint, etc.); supports ${ENV_VAR} values",
-    },
-  },
-};