kernl 0.8.3 → 0.9.0

package/dist/api/resources/agents/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../../src/api/resources/agents/agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;GAMG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAEzD;;;;;OAKG;IACH,GAAG,CACD,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,eAAe,GAAG,UAAU,EAC5C,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,SAAS;IAKnD;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;;;;OAKG;IACH,IAAI,IAAI,KAAK,CAAC,cAAc,EAAE,eAAe,CAAC,EAAE;IAOhD;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAGhC"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../../src/api/resources/agents/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC;IAE7D;;;;;;;OAOG;IACH,GAAG,CACD,QAAQ,GAAG,cAAc,EACzB,OAAO,SAAS,eAAe,GAAG,UAAU,EAC5C,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,SAAS;IAQnD;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;OAEG;IACH,IAAI,IAAI,KAAK,CAAC,cAAc,EAAE,eAAe,CAAC,EAAE;IAMhD;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAGhC"}

package/dist/api/resources/agents/agents.js

@@ -4,6 +4,10 @@
  * Thin facade over the in-process agent registry, returning live Agent instances.
  *
  * Note: agents are code, not persisted data; this is process-local.
+ *
+ * Currently only exposes LLM agents (kind: "llm"). RealtimeAgents are stored
+ * in the internal registry but not returned by these methods. If public access
+ * to realtime agents is needed, add a separate `kernl.realtimeAgents` resource.
  */
 export class RAgents {
     registry;
@@ -13,27 +17,29 @@ export class RAgents {
     /**
      * Get a live Agent instance by id.
      *
+     * Only returns LLM agents. Returns undefined for realtime agents.
+     *
      * Callers are expected to know the concrete TContext/TOutput types
      * for their own agents and can specify them via generics.
      */
     get(id) {
         const agent = this.registry.get(id);
-        return agent;
+        if (agent?.kind === "llm") {
+            return agent;
+        }
+        return undefined;
     }
     /**
-     * Check if an agent with the given id is registered.
+     * Check if an LLM agent with the given id is registered.
      */
     has(id) {
-        return this.registry.has(id);
+        return this.registry.get(id)?.kind === "llm";
     }
     /**
-     * List all registered agents as live instances.
-     *
-     * Since this is a heterogeneous collection, we expose the widest safe
-     * type parameters here.
+     * List all registered LLM agents as live instances.
      */
     list() {
-        return Array.from(this.registry.values());
+        return Array.from(this.registry.values()).filter((a) => a.kind === "llm");
     }
     /**
      * Unregister an agent at runtime.

package/dist/kernl/__tests__/memory-config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memory-config.test.d.ts.map

package/dist/kernl/__tests__/memory-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-config.test.d.ts","sourceRoot":"","sources":["../../../src/kernl/__tests__/memory-config.test.ts"],"names":[],"mappings":""}

package/dist/kernl/__tests__/memory-config.test.js

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { Kernl } from "../kernl.js";
+import { Agent } from "../../agent.js";
+import { logger } from "../../lib/logger.js";
+function createMockLanguageModel() {
+    return {
+        spec: "1.0",
+        provider: "test",
+        modelId: "test-model",
+    };
+}
+function createMockEmbeddingModel() {
+    return {
+        provider: "test",
+        modelId: "test-embedder",
+        embed: vi.fn(async ({ values }) => ({
+            embeddings: values.map((v) => [v.length, 0, 0]),
+        })),
+    };
+}
+function createMockVectorIndex() {
+    return {
+        id: "mock",
+        capabilities: () => ({
+            namespacing: false,
+            filtering: { basic: true },
+            hybrid: false,
+        }),
+        createIndex: vi.fn(),
+        deleteIndex: vi.fn(),
+        upsert: vi.fn(),
+        query: vi.fn(),
+        delete: vi.fn(),
+    };
+}
+describe("Kernl memory config warnings", () => {
+    let warnSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(logger, "warn").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        warnSpy.mockRestore();
+    });
+    it("warns when agent enables memory but no embedding configured", () => {
+        const kernl = new Kernl({
+            storage: {
+                vector: createMockVectorIndex(),
+            },
+            // no memory.embedding
+        });
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test Agent",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            memory: { enabled: true },
+        });
+        kernl.register(agent);
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Embeddings are not configured"));
+    });
+    it("warns when agent enables memory but no vector storage configured", () => {
+        const kernl = new Kernl({
+            memory: {
+                embedding: createMockEmbeddingModel(),
+            },
+            // no storage.vector
+        });
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test Agent",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            memory: { enabled: true },
+        });
+        kernl.register(agent);
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("No vector storage configured"));
+    });
+    it("warns for both missing embedding and vector storage", () => {
+        const kernl = new Kernl({});
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test Agent",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            memory: { enabled: true },
+        });
+        kernl.register(agent);
+        expect(warnSpy).toHaveBeenCalledTimes(2);
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Embeddings are not configured"));
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("No vector storage configured"));
+    });
+    it("warns only once across multiple agents", () => {
+        const kernl = new Kernl({});
+        const agent1 = new Agent({
+            id: "agent-1",
+            name: "Agent 1",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            memory: { enabled: true },
+        });
+        const agent2 = new Agent({
+            id: "agent-2",
+            name: "Agent 2",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            memory: { enabled: true },
+        });
+        kernl.register(agent1);
+        kernl.register(agent2);
+        // Should only warn twice total (once for embedding, once for vector)
+        // not four times (twice per agent)
+        expect(warnSpy).toHaveBeenCalledTimes(2);
+    });
+    it("does not warn when memory config is complete", () => {
+        const kernl = new Kernl({
+            storage: {
+                vector: createMockVectorIndex(),
+            },
+            memory: {
+                embedding: createMockEmbeddingModel(),
+            },
+        });
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test Agent",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            memory: { enabled: true },
+        });
+        kernl.register(agent);
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+    it("does not warn when agent does not enable memory", () => {
+        const kernl = new Kernl({});
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test Agent",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            memory: { enabled: false },
+        });
+        kernl.register(agent);
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+    it("does not warn when agent has no memory config", () => {
+        const kernl = new Kernl({});
+        const agent = new Agent({
+            id: "test-agent",
+            name: "Test Agent",
+            instructions: "test",
+            model: createMockLanguageModel(),
+            // no memory config at all
+        });
+        kernl.register(agent);
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+});

package/dist/kernl/kernl.d.ts

@@ -1,4 +1,4 @@
-import { Agent } from "../agent.js";
+import { BaseAgent } from "../agent/base.js";
 import { UnknownContext } from "../context.js";
 import { KernlHooks } from "../lifecycle.js";
 import type { Thread } from "../thread/index.js";
@@ -21,6 +21,9 @@ export declare class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
     private readonly _models;
     readonly storage: KernlStorage;
     athreads: Map<string, Thread<any, any>>;
+    private readonly _memopts;
+    private readonly _storopts;
+    private warnings;
     readonly threads: RThreads;
     readonly agents: RAgents;
     readonly memories: Memory;
@@ -28,7 +31,7 @@ export declare class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
     /**
      * Registers a new agent with the kernl instance.
      */
-    register(agent: Agent): void;
+    register(agent: BaseAgent): void;
     /**
      * Spawn a new thread - blocking execution
      */
@@ -51,5 +54,11 @@ export declare class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
      * Schedule an existing thread - streaming execution
      */
     scheduleStream<TContext, TOutput extends AgentOutputType>(thread: Thread<TContext, TOutput>): AsyncIterable<ThreadStreamEvent>;
+    /**
+     * @internal
+     *
+     * Initialize the memory system based on the storage + memory configuration.
+     */
+    private initializeMemory;
 }
 //# sourceMappingURL=kernl.d.ts.map

package/dist/kernl/kernl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernl.d.ts","sourceRoot":"","sources":["../../src/kernl/kernl.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EACL,MAAM,EAIP,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;GAKG;AACH,qBAAa,KAAM,SAAQ,UAAU,CAAC,cAAc,EAAE,eAAe,CAAC;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAa;IAGpD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,GAAE,YAAiB;IAoCtC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAa5B;;OAEG;IACG,KAAK,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EACnD,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IAS/D;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EACtD,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IAS/D;;;;OAIG;IACI,WAAW,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EAC1D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,aAAa,CAAC,iBAAiB,CAAC;IASnC;;;;OAIG;IACI,cAAc,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EAC7D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,aAAa,CAAC,iBAAiB,CAAC;CAQpC"}
+{"version":3,"file":"kernl.d.ts","sourceRoot":"","sources":["../../src/kernl/kernl.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EACL,MAAM,EAIP,MAAM,UAAU,CAAC;AAIlB,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAiC,MAAM,SAAS,CAAC;AAE3E;;;;;GAKG;AACH,qBAAa,KAAM,SAAQ,UAAU,CAAC,cAAc,EAAE,eAAe,CAAC;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAa;IAEpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IAEvD,OAAO,CAAC,QAAQ,CAGd;IAGF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,GAAE,YAAiB;IAatC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAgChC;;OAEG;IACG,KAAK,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EACnD,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IAS/D;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EACtD,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC;IAS/D;;;;OAIG;IACI,WAAW,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EAC1D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,aAAa,CAAC,iBAAiB,CAAC;IASnC;;;;OAIG;IACI,cAAc,CAAC,QAAQ,EAAE,OAAO,SAAS,eAAe,EAC7D,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAChC,aAAa,CAAC,iBAAiB,CAAC;IAWnC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CA6BzB"}

package/dist/kernl/kernl.js

@@ -4,6 +4,7 @@ import { InMemoryStorage } from "../storage/index.js";
 import { RThreads } from "../api/resources/threads/index.js";
 import { RAgents } from "../api/resources/agents/index.js";
 import { Memory, MemoryByteEncoder, MemoryIndexHandle, buildMemoryIndexSchema, } from "../memory/index.js";
+import { logger } from "../lib/logger.js";
 /**
  * The kernl - manages agent processes, scheduling, and task lifecycle.
  *
@@ -15,38 +16,25 @@ export class Kernl extends KernlHooks {
     _models = new Map();
     storage;
     athreads = new Map(); /* active threads */
+    _memopts;
+    _storopts;
+    warnings = {
+        embedding: false, // "Embeddings are not configured. If you want memories to auto-embed text content..."
+        vector: false, // "No vector storage configured. The memories.search() function will not be..."
+    }; /* tracks warnings that have been logged */
     // --- public API ---
     threads;
     agents;
     memories;
     constructor(options = {}) {
         super();
+        this._memopts = options.memory;
+        this._storopts = options.storage;
         this.storage = options.storage?.db ?? new InMemoryStorage();
         this.storage.bind({ agents: this._agents, models: this._models });
         this.threads = new RThreads(this.storage.threads);
         this.agents = new RAgents(this._agents);
-        // initialize memory
-        const embeddingModel = options.memory?.embeddingModel ?? "openai/text-embedding-3-small";
-        const embedder = typeof embeddingModel === "string"
-            ? resolveEmbeddingModel(embeddingModel)
-            : embeddingModel;
-        const encoder = new MemoryByteEncoder(embedder);
-        const vector = options.storage?.vector;
-        const indexId = options.memory?.indexId ?? "memories_sindex";
-        const dimensions = options.memory?.dimensions ?? 1536;
-        const providerOptions = options.memory?.indexProviderOptions ?? { schema: "kernl" };
-        this.memories = new Memory({
-            store: this.storage.memories,
-            search: vector !== undefined
-                ? new MemoryIndexHandle({
-                    index: vector,
-                    indexId,
-                    schema: buildMemoryIndexSchema({ dimensions }),
-                    providerOptions,
-                })
-                : undefined,
-            encoder,
-        });
+        this.memories = this.initializeMemory();
     }
     /**
      * Registers a new agent with the kernl instance.
@@ -54,12 +42,25 @@ export class Kernl extends KernlHooks {
     register(agent) {
         this._agents.set(agent.id, agent);
         agent.bind(this);
-        // (TODO): implement exhaustive model registry in protocol/ package
-        //
-        // auto-populate model registry for storage hydration
-        const key = `${agent.model.provider}/${agent.model.modelId}`;
-        if (!this._models.has(key)) {
-            this._models.set(key, agent.model);
+        // memory config warnings (log once)
+        if (agent.memory.enabled) {
+            if (!this._memopts?.embedding && !this.warnings.embedding) {
+                logger.warn("Embeddings are not configured. If you want memories to auto-embed text content, " +
+                    "pass an embedding model into the memory config in new Kernl()");
+                this.warnings.embedding = true;
+            }
+            if (!this._storopts?.vector && !this.warnings.vector) {
+                logger.warn("No vector storage configured. The memories.search() function will not be " +
+                    "available. To enable memory search, pass storage.vector in new Kernl()");
+                this.warnings.vector = true;
+            }
+        }
+        // auto-populate model registry for storage hydration (llm agents only - for now)
+        if (agent.kind === "llm") {
+            const key = `${agent.model.provider}/${agent.model.modelId}`;
+            if (!this._models.has(key)) {
+                this._models.set(key, agent.model);
+            }
         }
     }
     /**
@@ -116,4 +117,37 @@ export class Kernl extends KernlHooks {
             this.athreads.delete(thread.tid);
         }
     }
+    // --- private utils ---
+    /**
+     * @internal
+     *
+     * Initialize the memory system based on the storage + memory configuration.
+     */
+    initializeMemory() {
+        const embeddingModel = this._memopts?.embedding;
+        const embedder = embeddingModel
+            ? typeof embeddingModel === "string"
+                ? resolveEmbeddingModel(embeddingModel)
+                : embeddingModel
+            : undefined;
+        const encoder = new MemoryByteEncoder(embedder);
+        const vector = this._storopts?.vector;
+        const indexId = this._memopts?.indexId ?? "memories_sindex";
+        const dimensions = this._memopts?.dimensions ?? 1536;
+        const providerOptions = this._memopts?.indexProviderOptions ?? {
+            schema: "kernl",
+        };
+        return new Memory({
+            store: this.storage.memories,
+            search: vector
+                ? new MemoryIndexHandle({
+                    index: vector,
+                    indexId,
+                    schema: buildMemoryIndexSchema({ dimensions }),
+                    providerOptions,
+                })
+                : undefined,
+            encoder,
+        });
+    }
 }

package/dist/kernl/types.d.ts

@@ -1,6 +1,6 @@
 import { LanguageModel, EmbeddingModel } from "@kernl-sdk/protocol";
 import { SearchIndex } from "@kernl-sdk/retrieval";
-import { Agent } from "../agent.js";
+import { BaseAgent } from "../agent/base.js";
 import { KernlStorage } from "../storage/index.js";
 /**
  * Storage configuration for Kernl.
@@ -27,9 +27,10 @@ export interface MemoryOptions {
      * - A string like "openai/text-embedding-3-small" (resolved via provider registry)
      * - An EmbeddingModel instance
      *
-     * @default "openai/text-embedding-3-small"
+     * If not provided, memories will not auto-embed text content and
+     * semantic search will not be available.
      */
-    embeddingModel?: string | EmbeddingModel<string>;
+    embedding?: string | EmbeddingModel<string>;
     /**
      * Logical index ID used by the search backend.
      * - For pgvector: becomes the table name (with schema from indexProviderOptions)
@@ -71,10 +72,10 @@ export interface KernlOptions {
 /**
  * Agent registry interface.
  *
- * Satisfied by Map<string, Agent>.
+ * Satisfied by Map<string, BaseAgent>.
  */
 export interface AgentRegistry {
-    get(id: string): Agent<any> | undefined;
+    get(id: string): BaseAgent<any> | undefined;
 }
 /**
  * Model registry interface.

package/dist/kernl/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/kernl/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,EAAE,CAAC,EAAE,YAAY,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CAKtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/C;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;OAEG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;CAC7C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/kernl/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,EAAE,CAAC,EAAE,YAAY,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CAKtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/C;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,aAAa,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;OAEG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;CAC7C"}

package/dist/lib/env.d.ts

@@ -7,11 +7,11 @@ import { z } from "zod";
  */
 declare const envSchema: z.ZodObject<{
     LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        error: "error";
         trace: "trace";
         debug: "debug";
         info: "info";
         warn: "warn";
-        error: "error";
         fatal: "fatal";
     }>>;
     KERNL_LOG_MODEL_DATA: z.ZodPipe<z.ZodOptional<z.ZodEnum<{
@@ -31,7 +31,7 @@ declare const envSchema: z.ZodObject<{
  * console.log(env.LOG_LEVEL);
  */
 export declare const env: {
-    LOG_LEVEL: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    LOG_LEVEL: "error" | "trace" | "debug" | "info" | "warn" | "fatal";
     KERNL_LOG_MODEL_DATA: boolean;
     KERNL_LOG_TOOL_DATA: boolean;
 };

package/dist/mcp/__tests__/utils.test.js

@@ -52,7 +52,7 @@ describe("mcpToFunctionTool", () => {
         expect(functionTool.description).toBe("Performs calculations");
         expect(functionTool.parameters).toBeDefined();
     });
-    it("should handle tools without inputSchema (undefined parameters)", () => {
+    it("should handle tools without inputSchema (empty object parameters)", () => {
         const server = createMockServer();
         // In practice, MCP SDK tools require inputSchema, but our function handles
         // the case where it might not be present. We use 'as any' to test this edge case.
@@ -62,7 +62,9 @@ describe("mcpToFunctionTool", () => {
         };
         const functionTool = mcpToFunctionTool(server, mcpTool);
         expect(functionTool.id).toBe("no_params");
-        expect(functionTool.parameters).toBeUndefined();
+        // When no inputSchema, we use an empty z.object({}) to match AI SDK behavior
+        expect(functionTool.parameters).toBeDefined();
+        expect(functionTool.parameters?.def.type).toBe("object");
     });
     it("should invoke server.callTool with correct params", async () => {
         const server = createMockServer();

package/dist/mcp/utils.d.ts

@@ -5,7 +5,7 @@ import type { MCPTool, MCPToolFilter } from "./types.js";
 /**
  * Converts an MCP tool definition into a function tool usable by the SDK.
  */
-export declare function mcpToFunctionTool(server: MCPServer, mcpTool: MCPTool): import("../tool/index.js").FunctionTool<unknown, z.ZodObject<{}, z.core.$strip>, {
+export declare function mcpToFunctionTool(server: MCPServer, mcpTool: MCPTool): import("../tool/tool.js").FunctionTool<unknown, z.ZodObject<{}, z.core.$strip>, {
     type: string;
     text: string;
 } | {

package/dist/mcp/utils.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { tool } from "../tool/index.js";
+import { tool } from "../tool/tool.js";
 /**
  * Converts an MCP tool definition into a function tool usable by the SDK.
  */

package/dist/memory/__tests__/encoder.test.js

@@ -117,5 +117,51 @@ describe("MemoryByteEncoder", () => {
             const vec = await encoder.embed("search query");
             expect(vec).toEqual([12, 0, 0]); // "search query".length = 12
         });
+        it("returns null when no embedder configured", async () => {
+            const encoder = new MemoryByteEncoder(); // no embedder
+            const vec = await encoder.embed("search query");
+            expect(vec).toBeNull();
+        });
+        it("throws when embedder returns empty embedding", async () => {
+            const embedder = {
+                provider: "test",
+                modelId: "test-embedder",
+                embed: vi.fn(async () => ({
+                    embeddings: [[]], // empty embedding
+                })),
+            };
+            const encoder = new MemoryByteEncoder(embedder);
+            await expect(encoder.embed("test")).rejects.toThrow("Embedder returned empty embedding");
+        });
+        it("throws when embedder returns undefined embedding", async () => {
+            const embedder = {
+                provider: "test",
+                modelId: "test-embedder",
+                embed: vi.fn(async () => ({
+                    embeddings: [], // no embeddings at all
+                })),
+            };
+            const encoder = new MemoryByteEncoder(embedder);
+            await expect(encoder.embed("test")).rejects.toThrow("Embedder returned empty embedding");
+        });
+    });
+    describe("without embedder", () => {
+        it("returns undefined tvec when encoding with no embedder", async () => {
+            const encoder = new MemoryByteEncoder(); // no embedder
+            const byte = { text: "Hello world" };
+            const result = await encoder.encode(byte);
+            expect(result.text).toBe("Hello world");
+            expect(result.tvec).toBeUndefined();
+        });
+        it("still produces objtext projection without embedder", async () => {
+            const encoder = new MemoryByteEncoder(); // no embedder
+            const byte = {
+                object: { preference: "coffee", shots: 2 },
+            };
+            const result = await encoder.encode(byte);
+            expect(result.text).toContain("preference: coffee");
+            expect(result.objtext).toContain("preference: coffee");
+            expect(result.tvec).toBeUndefined();
+        });
     });
 });

package/dist/memory/codecs/domain.js

@@ -95,8 +95,7 @@ export const PATCH_CODEC = {
             patch.timestamp = update.timestamp;
         if (update.updatedAt !== undefined)
             patch.updatedAt = update.updatedAt;
-        if (update.metadata !== undefined)
-            patch.metadata = update.metadata;
+        // metadata is stored in primary DB only, not indexed
         return patch;
     },
     decode(_patch) {

package/dist/memory/encoder.d.ts

@@ -24,19 +24,17 @@ export declare const ObjectTextCodec: {
  * Encoder that converts MemoryByte to IndexableByte.
  *
  * Extracts canonical text from content and computes embeddings.
+ * If no embedder is provided, skips embedding and tvec will be undefined.
  */
 export declare class MemoryByteEncoder implements MemoryByteCodec {
-    private readonly embedder;
-    constructor(embedder: EmbeddingModel<string>);
+    private readonly embedder?;
+    constructor(embedder?: EmbeddingModel<string>);
     /**
      * Encode a MemoryByte to IndexableByte.
      *
      * - Produces `objtext` string projection for FTS indexing
      * - Combines text + objtext for embedding input
      * - Returns text (fallback to objtext if no text provided)
-     *
-     * Note: metadata is NOT set here - it comes from record.metadata
-     * via the domain codec, not from MemoryByte.object.
      */
     encode(byte: MemoryByte): Promise<IndexableByte>;
     /**
@@ -45,8 +43,10 @@ export declare class MemoryByteEncoder implements MemoryByteCodec {
     decode(_indexable: IndexableByte): Promise<MemoryByte>;
     /**
      * Embed a text string.
-     * Exposed for query embedding.
+     *
+     * @returns Embedding vector, or null if no embedder configured.
+     * @throws If embedder returns empty embedding.
      */
-    embed(text: string): Promise<number[]>;
+    embed(text: string): Promise<number[] | null>;
 }
 //# sourceMappingURL=encoder.d.ts.map

package/dist/memory/encoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/memory/encoder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtE,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAQ1E;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;OAIG;gBACS,UAAU,GAAG,MAAM;CAOhC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAEtC,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC;IAI5C;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAwBtD;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;IAI5D;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAI7C"}
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/memory/encoder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtE,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAQ1E;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;OAIG;gBACS,UAAU,GAAG,MAAM;CAOhC,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAyB;gBAEvC,QAAQ,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC;IAI7C;;;;;;OAMG;IACG,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAyBtD;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;IAI5D;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;CAWpD"}