kernl 0.8.2 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -33,7 +33,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
-    "pino": "^9.6.0",
     "yaml": "^2.8.2",
     "zod": "^4.1.12",
     "@kernl-sdk/protocol": "0.2.8",

package/src/kernl/__tests__/memory-config.test.ts

@@ -0,0 +1,203 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { LanguageModel, EmbeddingModel } from "@kernl-sdk/protocol";
+import type { SearchIndex } from "@kernl-sdk/retrieval";
+
+import { Kernl } from "../kernl";
+import { Agent } from "@/agent";
+import { logger } from "@/lib/logger";
+
+function createMockLanguageModel(): LanguageModel {
+  return {
+    spec: "1.0" as const,
+    provider: "test",
+    modelId: "test-model",
+  } as unknown as LanguageModel;
+}
+
+function createMockEmbeddingModel(): EmbeddingModel<string> {
+  return {
+    provider: "test",
+    modelId: "test-embedder",
+    embed: vi.fn(async ({ values }: { values: string[] }) => ({
+      embeddings: values.map((v) => [v.length, 0, 0]),
+    })),
+  } as unknown as EmbeddingModel<string>;
+}
+
+function createMockVectorIndex(): SearchIndex {
+  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(),
+  } as unknown as SearchIndex;
+}
+
+describe("Kernl memory config warnings", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  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/src/kernl/kernl.ts

@@ -16,10 +16,11 @@ import {
   buildMemoryIndexSchema,
 } from "@/memory";
 
+import { logger } from "@/lib/logger";
+
 import type { ThreadExecuteResult, ThreadStreamEvent } from "@/thread/types";
 import type { AgentOutputType } from "@/agent/types";
-
-import type { KernlOptions } from "./types";
+import type { KernlOptions, MemoryOptions, StorageOptions } from "./types";
 
 /**
  * The kernl - manages agent processes, scheduling, and task lifecycle.
@@ -34,6 +35,14 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
   readonly storage: KernlStorage;
   athreads: Map<string, Thread<any, any>> = new Map(); /* active threads */
 
+  private readonly _memopts: MemoryOptions | undefined;
+  private readonly _storopts: StorageOptions | undefined;
+
+  private 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 ---
   readonly threads: RThreads;
   readonly agents: RAgents;
@@ -41,38 +50,15 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
 
   constructor(options: KernlOptions = {}) {
     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<string>(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();
   }
 
   /**
@@ -82,6 +68,25 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
     this._agents.set(agent.id, agent);
     agent.bind(this);
 
+    // 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;
+      }
+    }
+
     // (TODO): implement exhaustive model registry in protocol/ package
     //
     // auto-populate model registry for storage hydration
@@ -152,4 +157,41 @@ export class Kernl extends KernlHooks<UnknownContext, AgentOutputType> {
       this.athreads.delete(thread.tid);
     }
   }
+
+  // --- private utils ---
+
+  /**
+   * @internal
+   *
+   * Initialize the memory system based on the storage + memory configuration.
+   */
+  private initializeMemory(): Memory {
+    const embeddingModel = this._memopts?.embedding;
+    const embedder = embeddingModel
+      ? typeof embeddingModel === "string"
+        ? resolveEmbeddingModel<string>(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/src/kernl/types.ts

@@ -35,9 +35,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.

package/src/lib/logger.ts

@@ -1,26 +1,5 @@
-import pino from "pino";
-
 import { env } from "./env";
 
-/**
- * By default we don't log LLM inputs/outputs, to prevent exposing sensitive data.
- * Set KERNL_LOG_MODEL_DATA=true to enable.
- */
-const dontLogModelData = !env.KERNL_LOG_MODEL_DATA;
-
-/**
- * By default we don't log tool inputs/outputs, to prevent exposing sensitive data.
- * Set KERNL_LOG_TOOL_DATA=true to enable.
- */
-const dontLogToolData = !env.KERNL_LOG_TOOL_DATA;
-
-/**
- * Base pino logger instance
- */
-const base = pino({
-  level: env.LOG_LEVEL,
-});
-
 /**
  * A logger instance with namespace support and sensitive data flags.
  */
@@ -52,21 +31,21 @@ export type Logger = {
  * Get a logger for a given namespace.
  *
  * @param namespace - the namespace to use for the logger (e.g., 'kernl:core', 'kernl:agent').
- * @returns A logger object with all pino log levels and sensitive data flags.
+ * @returns A logger object with console-based logging and sensitive data flags.
  */
 export function getLogger(namespace: string = "kernl"): Logger {
-  const child = base.child({ namespace });
+  const prefix = `[${namespace}]`;
 
   return {
     namespace,
-    trace: child.trace.bind(child),
-    debug: child.debug.bind(child),
-    info: child.info.bind(child),
-    warn: child.warn.bind(child),
-    error: child.error.bind(child),
-    fatal: child.fatal.bind(child),
-    dontLogModelData,
-    dontLogToolData,
+    trace: (msg, ...args) => console.debug(prefix, msg, ...args),
+    debug: (msg, ...args) => console.debug(prefix, msg, ...args),
+    info: (msg, ...args) => console.info(prefix, msg, ...args),
+    warn: (msg, ...args) => console.warn(prefix, msg, ...args),
+    error: (msg, ...args) => console.error(prefix, msg, ...args),
+    fatal: (msg, ...args) => console.error(prefix, "[FATAL]", msg, ...args),
+    dontLogModelData: !env.KERNL_LOG_MODEL_DATA,
+    dontLogToolData: !env.KERNL_LOG_TOOL_DATA,
   };
 }
 

package/src/memory/__tests__/encoder.test.ts

@@ -150,5 +150,68 @@ describe("MemoryByteEncoder", () => {
 
       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
+        })),
+      } as unknown as EmbeddingModel<string>;
+      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
+        })),
+      } as unknown as EmbeddingModel<string>;
+      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: MemoryByte = { 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: MemoryByte = {
+        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/src/memory/codecs/domain.ts

@@ -110,7 +110,7 @@ export const PATCH_CODEC: Codec<MemoryRecordUpdate, IndexMemoryRecordPatch> = {
     if (update.collection !== undefined) patch.collection = update.collection;
     if (update.timestamp !== undefined) 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;
   },

package/src/memory/encoder.ts

@@ -41,11 +41,12 @@ export 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 class MemoryByteEncoder implements MemoryByteCodec {
-  private readonly embedder: EmbeddingModel<string>;
+  private readonly embedder?: EmbeddingModel<string>;
 
-  constructor(embedder: EmbeddingModel<string>) {
+  constructor(embedder?: EmbeddingModel<string>) {
     this.embedder = embedder;
   }
 
@@ -55,9 +56,6 @@ export class MemoryByteEncoder implements MemoryByteCodec {
    * - 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.
    */
   async encode(byte: MemoryByte): Promise<IndexableByte> {
     const objtext = byte.object
@@ -67,8 +65,9 @@ export class MemoryByteEncoder implements MemoryByteCodec {
     // (TODO): this behavior deserves consideration - do we always want to merge text + object?
     //
     // combine text + object for richer embedding
+    // skip embedding if no embedder configured (embed returns null)
     const combined = [byte.text, objtext].filter(Boolean).join("\n");
-    const tvec = combined ? await this.embed(combined) : undefined;
+    const tvec = combined ? await this.embed(combined) : null;
 
     // TODO: embed other modalities (image, audio, video)
     //
@@ -79,7 +78,7 @@ export class MemoryByteEncoder implements MemoryByteCodec {
     return {
       text: byte.text ?? objtext, // fallback to projection if no text
       objtext,
-      tvec,
+      tvec: tvec ?? undefined,
     };
   }
 
@@ -92,10 +91,19 @@ export class MemoryByteEncoder implements MemoryByteCodec {
 
   /**
    * Embed a text string.
-   * Exposed for query embedding.
+   *
+   * @returns Embedding vector, or null if no embedder configured.
+   * @throws If embedder returns empty embedding.
    */
-  async embed(text: string): Promise<number[]> {
+  async embed(text: string): Promise<number[] | null> {
+    if (!this.embedder) {
+      return null;
+    }
     const result = await this.embedder.embed({ values: [text] });
-    return result.embeddings[0] ?? [];
+    const embedding = result.embeddings[0];
+    if (!embedding || embedding.length === 0) {
+      throw new Error("Embedder returned empty embedding");
+    }
+    return embedding;
   }
 }

package/src/memory/memory.ts

@@ -95,7 +95,7 @@ export class Memory {
     const tvec = await this.encoder.embed(q.query);
 
     return this._search.query({
-      query: [{ text: q.query, tvec }],
+      query: [{ text: q.query, tvec: tvec ?? undefined }],
       filter: q.filter ? MEMORY_FILTER.encode(q.filter) : undefined,
       topK: q.limit ?? 20,
     });

package/src/memory/types.ts

@@ -75,7 +75,12 @@ export interface IndexableByte {
  * Encoder that converts MemoryByte to IndexableByte with embeddings.
  */
 export interface MemoryByteCodec extends AsyncCodec<MemoryByte, IndexableByte> {
-  embed(text: string): Promise<number[]>;
+  /**
+   * Embed a text string.
+   *
+   * @returns Embedding vector, or null if no embedder configured.
+   */
+  embed(text: string): Promise<number[] | null>;
 }
 
 // -------------------
@@ -294,5 +299,4 @@ export interface IndexMemoryRecordPatch {
   collection?: string;
   timestamp?: number;
   updatedAt?: number;
-  metadata?: JSONObject | null;
 }

package/.turbo/turbo-check-types.log

@@ -1,4 +0,0 @@
-
-> kernl@0.6.2 check-types /Users/andjones/Documents/projects/kernl/packages/kernl
-> tsc --noEmit
-

package/dist/memory/codec.d.ts

@@ -1,32 +0,0 @@
-/**
- * Memory codecs.
- */
-import type { Codec, AsyncCodec } from "@kernl-sdk/shared/lib";
-import type { Filter as SearchFilter } from "@kernl-sdk/retrieval";
-import type { MemoryFilter, MemoryRecord, MemoryRecordUpdate, IndexMemoryRecord, IndexMemoryRecordPatch, MemoryByteCodec } from "./types.js";
-/**
- * Codec for converting MemoryFilter to retrieval Filter.
- *
- * - scope.namespace → namespace
- * - scope.entityId → entityId
- * - scope.agentId → agentId
- * - collections → collection: { $in: [...] }
- * - after/before → timestamp: { $gt/$lt }
- *
- * Content field filtering (text, metadata, kind) is not currently supported.
- * Text relevance is handled via vector similarity in the query, not filters.
- */
-export declare const MEMORY_FILTER: Codec<MemoryFilter, SearchFilter>;
-/**
- * Create a codec for MemoryRecord -> IndexMemoryRecord.
- */
-export declare function recordCodec(bytecodec: MemoryByteCodec): AsyncCodec<MemoryRecord, IndexMemoryRecord>;
-/**
- * Codec for converting MemoryRecordUpdate to IndexMemoryRecordPatch.
- *
- * Maps patchable fields from domain update to index patch format.
- * wmem/smem are store-only fields and are not included.
- * content changes require full re-index, not a patch.
- */
-export declare const PATCH_CODEC: Codec<MemoryRecordUpdate, IndexMemoryRecordPatch>;
-//# sourceMappingURL=codec.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/memory/codec.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,YAAY,EAAE,YAAY,CA0B3D,CAAC;AAEF;;GAEG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,eAAe,GACzB,UAAU,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAqB7C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,kBAAkB,EAAE,sBAAsB,CAqBzE,CAAC"}