kernl 0.6.2 → 0.7.0

package/src/api/models/thread.ts

@@ -1,5 +1,5 @@
 import type { LanguageModelItem } from "@kernl-sdk/protocol";
-import type { ThreadState } from "@/types/thread";
+import type { ThreadState } from "@/thread/types";
 
 /**
  * Model metadata for the language model used by a thread.

package/src/api/resources/agents/agents.ts

@@ -0,0 +1,56 @@
+import type { Agent } from "@/agent";
+import type { AgentResponseType } from "@/agent/types";
+import type { UnknownContext } from "@/context";
+import type { TextResponse } from "@/thread/types";
+
+/**
+ * Agents resource.
+ *
+ * Thin facade over the in-process agent registry, returning live Agent instances.
+ *
+ * Note: agents are code, not persisted data; this is process-local.
+ */
+export class RAgents {
+  constructor(private readonly registry: Map<string, Agent>) {}
+
+  /**
+   * Get a live Agent instance by id.
+   *
+   * Callers are expected to know the concrete TContext/TResponse types
+   * for their own agents and can specify them via generics.
+   */
+  get<
+    TContext = UnknownContext,
+    TResponse extends AgentResponseType = TextResponse,
+  >(id: string): Agent<TContext, TResponse> | undefined {
+    const agent = this.registry.get(id);
+    return agent as Agent<TContext, TResponse> | undefined;
+  }
+
+  /**
+   * Check if an agent with the given id is registered.
+   */
+  has(id: string): boolean {
+    return this.registry.has(id);
+  }
+
+  /**
+   * List all registered agents as live instances.
+   *
+   * Since this is a heterogeneous collection, we expose the widest safe
+   * type parameters here.
+   */
+  list(): Agent<UnknownContext, AgentResponseType>[] {
+    return Array.from(this.registry.values()) as Agent<
+      UnknownContext,
+      AgentResponseType
+    >[];
+  }
+
+  /**
+   * Unregister an agent at runtime.
+   */
+  unregister(id: string): boolean {
+    return this.registry.delete(id);
+  }
+}

package/src/api/resources/agents/index.ts

@@ -0,0 +1 @@
+export { RAgents } from "./agents";

package/src/api/resources/threads/events.ts

@@ -1,7 +1,7 @@
 import type { ThreadStore } from "@/storage";
 import { isPublicEvent } from "@/thread/utils";
 import type { MThreadEvent } from "@/api/models";
-import type { ThreadEvent } from "@/types/thread";
+import type { ThreadEvent } from "@/thread/types";
 
 /**
  * Events subresource for threads.

package/src/api/resources/threads/threads.ts

@@ -3,14 +3,14 @@ import type {
   ThreadListOptions,
   ThreadHistoryOptions,
 } from "@/storage";
-import type { ThreadEvent } from "@/types/thread";
+import type { ThreadEvent } from "@/thread/types";
 import { isPublicEvent } from "@/thread/utils";
 import { Context } from "@/context";
 import { randomID } from "@kernl-sdk/shared/lib";
 import { RUNNING } from "@kernl-sdk/protocol";
 
 import type { MThread, MThreadEvent } from "@/api/models";
-import { CursorPage, type CursorPageResponse } from "@/api/pagination/cursor";
+import { CursorPage, type CursorPageResponse } from "@kernl-sdk/shared";
 
 import { RThreadEvents } from "./events";
 import type {

package/src/api/resources/threads/types.ts

@@ -1,6 +1,6 @@
-import type { ThreadState } from "@/types/thread";
+import type { ThreadState } from "@/thread/types";
 import type { SortOrder } from "@/storage";
-import type { CursorPageParams } from "@/api/pagination/cursor";
+import type { CursorPageParams } from "@kernl-sdk/shared";
 
 export interface RThreadHistoryParams {
   /**

package/src/context.ts

@@ -1,7 +1,9 @@
+import type { Agent } from "@/agent";
+
 /**
- * Status of a tool call approval.
+ * Context that is being passed around as part of the session is unknown
  */
-export type ApprovalStatus = "approved" | "rejected" | "pending";
+export type UnknownContext = unknown;
 
 /**
  * A propagation mechanism which carries execution-scoped values across API boundaries and between logically associated
@@ -12,12 +14,18 @@ export class Context<TContext = UnknownContext> {
    * The namespace that this context belongs to.
    */
   namespace: string;
-  
+
   /**
    * The inner context object.
    */
   context: TContext;
 
+  /**
+   * The agent executing this context.
+   * Set by the thread during execution.
+   */
+  agent?: Agent<TContext, any>;
+
   // ----------------------
   // TEMPORARY: Tool approval tracking until actions system is refined
   // ----------------------
@@ -64,10 +72,7 @@ export class Context<TContext = UnknownContext> {
   //  */
   // #approvals: Map<string, ApprovalRecord>;
 
-  constructor(
-    namespace: string = "kernl",
-    context: TContext = {} as TContext,
-  ) {
+  constructor(namespace: string = "kernl", context: TContext = {} as TContext) {
     this.namespace = namespace;
     this.context = context;
     this.approvals = new Map();
@@ -139,136 +144,9 @@ export class Context<TContext = UnknownContext> {
       // approvals: Object.fromEntries(this.#approvals.entries()),
     };
   }
-
-  // /**
-  //  * Rebuild the approvals map from a serialized state.
-  //  * @internal
-  //  *
-  //  * @param approvals - The approvals map to rebuild.
-  //  */
-  // _rebuildApprovals(approvals: Record<string, ApprovalRecord>) {
-  //   this.#approvals = new Map(Object.entries(approvals));
-  // }
-
-  // /**
-  //  * Check if a tool call has been approved.
-  //  *
-  //  * @param approval - Details about the tool call being evaluated.
-  //  * @returns `true` if the tool call has been approved, `false` if blocked and `undefined` if not yet approved or rejected.
-  //  */
-  // isToolApproved(approval: { toolName: string; callId: string }) {
-  //   const { toolName, callId } = approval;
-  //   const approvalEntry = this.#approvals.get(toolName);
-  //   if (approvalEntry?.approved === true && approvalEntry.rejected === true) {
-  //     logger.warn(
-  //       "Tool is permanently approved and rejected at the same time. Approval takes precedence",
-  //     );
-  //     return true;
-  //   }
-
-  //   if (approvalEntry?.approved === true) {
-  //     return true;
-  //   }
-
-  //   if (approvalEntry?.rejected === true) {
-  //     return false;
-  //   }
-
-  //   const individualCallApproval = Array.isArray(approvalEntry?.approved)
-  //     ? approvalEntry.approved.includes(callId)
-  //     : false;
-  //   const individualCallRejection = Array.isArray(approvalEntry?.rejected)
-  //     ? approvalEntry.rejected.includes(callId)
-  //     : false;
-
-  //   if (individualCallApproval && individualCallRejection) {
-  //     logger.warn(
-  //       `Tool call ${callId} is both approved and rejected at the same time. Approval takes precedence`,
-  //     );
-  //     return true;
-  //   }
-
-  //   if (individualCallApproval) {
-  //     return true;
-  //   }
-
-  //   if (individualCallRejection) {
-  //     return false;
-  //   }
-
-  //   return undefined;
-  // }
-
-  // /**
-  //  * Approve a tool call.
-  //  *
-  //  * @param approvalItem - The tool approval item to approve.
-  //  * @param options - Additional approval behavior options.
-  //  */
-  // approveTool(
-  //   approvalItem: RunToolApprovalItem,
-  //   { alwaysApprove = false }: { alwaysApprove?: boolean } = {},
-  // ) {
-  //   const toolName = approvalItem.rawItem.name;
-  //   if (alwaysApprove) {
-  //     this.#approvals.set(toolName, {
-  //       approved: true,
-  //       rejected: [],
-  //     });
-  //     return;
-  //   }
-
-  //   const approvalEntry = this.#approvals.get(toolName) ?? {
-  //     approved: [],
-  //     rejected: [],
-  //   };
-  //   if (Array.isArray(approvalEntry.approved)) {
-  //     // function tool has call_id, hosted tool call has id
-  //     const callId =
-  //       "callId" in approvalItem.rawItem
-  //         ? approvalItem.rawItem.callId // function tools
-  //         : approvalItem.rawItem.id!; // hosted tools
-  //     approvalEntry.approved.push(callId);
-  //   }
-  //   this.#approvals.set(toolName, approvalEntry);
-  // }
-
-  // /**
-  //  * Reject a tool call.
-  //  *
-  //  * @param approvalItem - The tool approval item to reject.
-  //  */
-  // rejectTool(
-  //   approvalItem: RunToolApprovalItem,
-  //   { alwaysReject = false }: { alwaysReject?: boolean } = {},
-  // ) {
-  //   const toolName = approvalItem.rawItem.name;
-  //   if (alwaysReject) {
-  //     this.#approvals.set(toolName, {
-  //       approved: false,
-  //       rejected: true,
-  //     });
-  //     return;
-  //   }
-
-  //   const approvalEntry = this.#approvals.get(toolName) ?? {
-  //     approved: [] as string[],
-  //     rejected: [] as string[],
-  //   };
-
-  //   if (Array.isArray(approvalEntry.rejected)) {
-  //     // function tool has call_id, hosted tool call has id
-  //     const callId =
-  //       "callId" in approvalItem.rawItem
-  //         ? approvalItem.rawItem.callId // function tools
-  //         : approvalItem.rawItem.id!; // hosted tools
-  //     approvalEntry.rejected.push(callId);
-  //   }
-  //   this.#approvals.set(toolName, approvalEntry);
-  // }
 }
 
 /**
- * Context that is being passed around as part of the session is unknown
+ * Status of a tool call approval.
  */
-export type UnknownContext = unknown;
+export type ApprovalStatus = "approved" | "rejected" | "pending";

package/src/guardrail.ts

@@ -4,8 +4,8 @@ import { LanguageModelResponse } from "@kernl-sdk/protocol";
 
 import { Agent } from "./agent";
 import { Context, UnknownContext } from "./context";
-import type { AgentResponseType } from "./types/agent";
-import type { TextResponse, ThreadEvent } from "./types/thread";
+import type { AgentResponseType } from "@/agent/types";
+import type { TextResponse, ThreadEvent } from "@/thread/types";
 
 /**
  * Resolves the agent output type based on the response type.

package/src/index.ts

@@ -4,24 +4,25 @@ export type {
   StorageOptions,
   AgentRegistry,
   ModelRegistry,
-} from "./types/kernl";
+} from "./kernl";
 export { Agent } from "./agent";
 export { Context } from "./context";
 
 // --- tools --
+
 export { tool, Toolkit, FunctionToolkit, MCPToolkit } from "./tool";
 export { MCPServerSSE } from "./mcp/sse";
 export { MCPServerStdio } from "./mcp/stdio";
 export { MCPServerStreamableHttp } from "./mcp/http";
 
-// --- thread models ---
+// --- threads ---
+
 export type {
   MThread as Thread,
   MThreadEvent as ThreadEvent,
   MThreadEventBase as ThreadEventBase,
 } from "./api/models";
 
-// --- thread resource types ---
 export type {
   RThreadsListParams as ThreadsListParams,
   RThreadGetOptions as ThreadGetOptions,
@@ -30,14 +31,14 @@ export type {
   RThreadUpdateParams as ThreadUpdateParams,
 } from "./api/resources/threads";
 
-// --- thread state enums ---
 export {
   THREAD_STATES,
   type ThreadState,
   type PublicThreadEvent,
-} from "./types/thread";
+} from "./thread/types";
+
+// --- storage ---
 
-// --- storage types ---
 export type {
   ThreadStore,
   NewThread,
@@ -50,3 +51,31 @@ export type {
   KernlStorage,
   Transaction,
 } from "./storage";
+
+// --- memory ---
+export { Memory, MemoryByteEncoder } from "./memory";
+export type {
+  MemoryStore,
+  MemoryScope,
+  NewMemory,
+  MemoryConfig,
+  MemoryReindexParams,
+  MemoryRecord,
+  MemoryKind,
+  MemoryRecordUpdate,
+  MemoryFilter,
+  MemoryListOptions,
+  MemorySearchQuery,
+  WorkingMemorySnapshot,
+  ShortTermMemorySnapshot,
+  MemoryIndexBase,
+  MemorySearchIndex,
+  MemoryGraphIndex,
+  MemoryArchiveIndex,
+  GraphTraversalQuery,
+  GraphTraversalResult,
+  ArchiveQuery,
+  ArchiveResult,
+  MemoryByte,
+  MemoryByteCodec,
+} from "./memory";

package/src/internal.ts

@@ -8,8 +8,8 @@ export type {
   ThreadSystemEvent,
   ThreadState,
   PublicThreadEvent,
-} from "./types/thread";
+} from "@/thread/types";
 
-export { THREAD_STATES } from "./types/thread";
+export { THREAD_STATES } from "@/thread/types";
 
 

package/src/kernl/index.ts

@@ -0,0 +1,8 @@
+export { Kernl } from "./kernl";
+export type {
+  KernlOptions,
+  StorageOptions,
+  MemoryOptions,
+  AgentRegistry,
+  ModelRegistry,
+} from "./types";

package/src/{kernl.ts → kernl/kernl.ts}

@@ -1,4 +1,5 @@
 import type { LanguageModel } from "@kernl-sdk/protocol";
+import { resolveEmbeddingModel } from "@kernl-sdk/retrieval";
 
 import { Agent } from "@/agent";
 import { UnknownContext } from "@/context";
@@ -7,10 +8,18 @@ import type { Thread } from "@/thread";
 import type { ResolvedAgentResponse } from "@/guardrail";
 import { InMemoryStorage, type KernlStorage } from "@/storage";
 import { RThreads } from "@/api/resources/threads";
+import { RAgents } from "@/api/resources/agents";
+import {
+  Memory,
+  MemoryByteEncoder,
+  MemoryIndexHandle,
+  buildMemoryIndexSchema,
+} from "@/memory";
 
-import type { KernlOptions } from "@/types/kernl";
-import type { ThreadExecuteResult, ThreadStreamEvent } from "@/types/thread";
-import type { AgentResponseType } from "@/types/agent";
+import type { ThreadExecuteResult, ThreadStreamEvent } from "@/thread/types";
+import type { AgentResponseType } from "@/agent/types";
+
+import type { KernlOptions } from "./types";
 
 /**
  * The kernl - manages agent processes, scheduling, and task lifecycle.
@@ -19,35 +28,66 @@ import type { AgentResponseType } from "@/types/agent";
  * tracing.
  */
 export class Kernl extends KernlHooks<UnknownContext, AgentResponseType> {
-  private agents: Map<string, Agent> = new Map();
-  private models: Map<string, LanguageModel> = new Map();
+  private readonly _agents: Map<string, Agent> = new Map();
+  private readonly _models: Map<string, LanguageModel> = new Map();
 
   readonly storage: KernlStorage;
   athreads: Map<string, Thread<any, any>> = new Map(); /* active threads */
 
   // --- public API ---
-  readonly threads: RThreads; /* Threads resource */
+  readonly threads: RThreads;
+  readonly agents: RAgents;
+  readonly memories: Memory;
 
   constructor(options: KernlOptions = {}) {
     super();
     this.storage = options.storage?.db ?? new InMemoryStorage();
-    this.storage.bind({ agents: this.agents, models: this.models });
+    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,
+    });
   }
 
   /**
    * Registers a new agent with the kernl instance.
    */
   register(agent: Agent): void {
-    this.agents.set(agent.id, 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);
+    if (!this._models.has(key)) {
+      this._models.set(key, agent.model);
     }
   }
 

package/src/kernl/types.ts

@@ -0,0 +1,106 @@
+import { LanguageModel, EmbeddingModel } from "@kernl-sdk/protocol";
+import { SearchIndex } from "@kernl-sdk/retrieval";
+
+import { Agent } from "@/agent";
+import { KernlStorage } from "@/storage";
+
+/**
+ * Storage configuration for Kernl.
+ */
+export interface StorageOptions {
+  /**
+   * Relational database storage (threads, tasks, traces).
+   */
+  db?: KernlStorage;
+
+  /**
+   * Vector search index for semantic memory search.
+   * Supports pgvector, Turbopuffer, etc.
+   */
+  vector?: SearchIndex;
+
+  // Future storage layers (deferred):
+  // blob?: BlobStore;
+  // lake?: DataLake;
+}
+
+/**
+ * Memory system configuration.
+ */
+export interface MemoryOptions {
+  /**
+   * Embedding model for memory encoding.
+   *
+   * Can be:
+   * - A string like "openai/text-embedding-3-small" (resolved via provider registry)
+   * - An EmbeddingModel instance
+   *
+   * @default "openai/text-embedding-3-small"
+   */
+  embeddingModel?: string | EmbeddingModel<string>;
+
+  /**
+   * Logical index ID used by the search backend.
+   * - For pgvector: becomes the table name (with schema from indexProviderOptions)
+   * - For Turbopuffer: becomes the namespace
+   * @default "kernl_memories_index"
+   */
+  indexId?: string;
+
+  /**
+   * Backend-specific options passed to SearchIndex.createIndex().
+   * - For pgvector: { schema?: string } controls schema (default: "kernl")
+   * - For Turbopuffer: not used
+   */
+  indexProviderOptions?: Record<string, unknown>;
+
+  /**
+   * Vector dimensions for embeddings.
+   * Only needed if embedding model doesn't provide this automatically.
+   * @default 1536
+   */
+  dimensions?: number;
+
+  /**
+   * Similarity metric for vector search.
+   * @default "cosine"
+   */
+  similarity?: "cosine" | "euclidean" | "dot_product";
+}
+
+/**
+ * Configuration options for creating a Kernl instance.
+ */
+export interface KernlOptions {
+  /**
+   * Storage configuration for persisting threads, tasks, and traces.
+   */
+  storage?: StorageOptions;
+
+  /**
+   * Memory system configuration.
+   */
+  memory?: MemoryOptions;
+}
+
+/**
+ * Agent registry interface.
+ *
+ * Satisfied by Map<string, Agent>.
+ */
+export interface AgentRegistry {
+  get(id: string): Agent<any> | undefined;
+}
+
+/**
+ * Model registry interface.
+ *
+ * Satisfied by Map<string, LanguageModel>.
+ * Key format: "provider/modelId"
+ *
+ * TODO: Create an exhaustive model registry in the protocol package
+ * with all supported models and their metadata.
+ */
+export interface ModelRegistry {
+  get(key: string): LanguageModel | undefined;
+}

package/src/lib/error.ts

@@ -9,8 +9,8 @@ import { randomID } from "@kernl-sdk/shared/lib";
 // import { SerializedThread } from "@/lib/serde/thread";
 type SerializedThread = any;
 
-import { AgentResponseType } from "@/types/agent";
-import { TextResponse } from "@/types/thread";
+import { AgentResponseType } from "@/agent/types";
+import { TextResponse } from "@/thread/types";
 
 /**
  * Abstract base class for all `kernl` errors

package/src/lifecycle.ts

@@ -5,8 +5,8 @@ import { Context, UnknownContext } from "./context";
 import { Tool } from "./tool";
 import type { ToolCall } from "@kernl-sdk/protocol";
 
-import { AgentResponseType } from "./types/agent";
-import { TextResponse } from "./types/thread";
+import { AgentResponseType } from "@/agent/types";
+import { TextResponse } from "@/thread/types";
 
 export type EventEmitterEvents = Record<string, any[]>;