kernl 0.8.3 → 0.9.0

package/dist/tool/toolkit.d.ts

@@ -1,4 +1,4 @@
-import type { Agent } from "../agent.js";
+import type { BaseAgent } from "../agent/base.js";
 import type { Context, UnknownContext } from "../context.js";
 import type { Tool } from "./index.js";
 import type { FunctionToolkitConfig, MCPToolkitConfig } from "./types.js";
@@ -20,12 +20,12 @@ export declare abstract class BaseToolkit<TContext = UnknownContext> {
     /**
      * The agent this toolkit is bound to (if any)
      */
-    protected agent?: Agent<TContext, any>;
+    protected agent?: BaseAgent<TContext>;
     /**
      * Bind this toolkit to an agent.
-     * Called by Agent constructor.
+     * Called by agent constructor.
      */
-    bind(agent: Agent<TContext, any>): void;
+    bind(agent: BaseAgent<TContext>): void;
     /**
      * Get a specific tool by its ID.
      *

package/dist/tool/toolkit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../../src/tool/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;AAC9B,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,8BAAsB,WAAW,CAAC,QAAQ,GAAG,cAAc;IACzD;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAEvC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,IAAI;IAIvC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAEpD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAErE;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe,CAC1B,QAAQ,GAAG,cAAc,CACzB,SAAQ,WAAW,CAAC,QAAQ,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,KAAK,CAA8B;IAE3C;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC;IAOnD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;CAGnE;AAED;;GAEG;AACH,OAAO,EAAE,eAAe,IAAI,OAAO,EAAE,CAAC;AAiCtC,qBAAa,UAAU,CACrB,QAAQ,GAAG,cAAc,CACzB,SAAQ,WAAW,CAAC,QAAQ,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAA0B;IAExC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IAS9C;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IA+BlE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}
+{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../../src/tool/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAMzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;AAC9B,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,8BAAsB,WAAW,CAAC,QAAQ,GAAG,cAAc;IACzD;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAEtC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI;IAItC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAEpD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAErE;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe,CAC1B,QAAQ,GAAG,cAAc,CACzB,SAAQ,WAAW,CAAC,QAAQ,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,KAAK,CAA8B;IAE3C;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC;IAOnD;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;OAKG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;CAGnE;AAED;;GAEG;AACH,OAAO,EAAE,eAAe,IAAI,OAAO,EAAE,CAAC;AAiCtC,qBAAa,UAAU,CACrB,QAAQ,GAAG,cAAc,CACzB,SAAQ,WAAW,CAAC,QAAQ,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAA0B;IAExC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC;IAS9C;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI3C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAgClE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}

package/dist/tool/toolkit.js

@@ -13,7 +13,7 @@ export class BaseToolkit {
     agent;
     /**
      * Bind this toolkit to an agent.
-     * Called by Agent constructor.
+     * Called by agent constructor.
      */
     bind(agent) {
         this.agent = agent;
@@ -159,6 +159,7 @@ export class MCPToolkit extends BaseToolkit {
         if (!this.cached) {
             const mcpTools = await this.server.listTools();
             for (const mcpTool of mcpTools) {
+                // safety: MCP tools are context-agnostic (external servers)
                 const tool = mcpToFunctionTool(this.server, mcpTool);
                 this.cache.set(tool.id, tool);
             }

package/dist/tool/types.d.ts

@@ -1,5 +1,5 @@
 import { z, type ZodType } from "zod";
-import { Agent } from "../agent.js";
+import type { BaseAgent } from "../agent/base.js";
 import { Context, UnknownContext } from "../context.js";
 import { MCPServer } from "../mcp/base.js";
 import type { ToolCallState } from "@kernl-sdk/protocol";
@@ -60,7 +60,7 @@ export type ToolConfig<TContext = UnknownContext, TParameters extends ToolInputP
  */
 export interface ToolkitFilterContext<TContext = UnknownContext> {
     context: Context<TContext>;
-    agent: Agent<TContext, any>;
+    agent: BaseAgent<TContext>;
     toolkitId: string;
 }
 /**
@@ -176,10 +176,10 @@ export type ToolExecuteFunction<TContext = UnknownContext, TParameters extends T
  * @returns True if the tool call should be approved, false otherwise
  */
 export type ToolApprovalFunction<TParameters extends ToolInputParameters> = (context: Context, input: ToolExecuteArgument<TParameters>, callId?: string) => Promise<boolean>;
-export type ToolEnabledFunction<TContext = UnknownContext> = (context: Context<TContext>, agent: Agent<any, any>) => Promise<boolean>;
+export type ToolEnabledFunction<TContext = UnknownContext> = (context: Context<TContext>, agent: BaseAgent<TContext>) => Promise<boolean>;
 export type ToolEnabledPredicate<TContext = UnknownContext> = (args: {
     context: Context<TContext>;
-    agent: Agent<any, any>;
+    agent: BaseAgent<TContext>;
 }) => boolean | Promise<boolean>;
 type ToolEnabledOption<Context = UnknownContext> = boolean | ToolEnabledPredicate<Context>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tool/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tool/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -35,8 +35,8 @@
     "@modelcontextprotocol/sdk": "^1.20.2",
     "yaml": "^2.8.2",
     "zod": "^4.1.12",
-    "@kernl-sdk/protocol": "0.2.8",
-    "@kernl-sdk/retrieval": "0.1.3",
+    "@kernl-sdk/protocol": "0.3.0",
+    "@kernl-sdk/retrieval": "0.1.4",
     "@kernl-sdk/shared": "^0.3.0"
   },
   "devDependencies": {
@@ -45,7 +45,7 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/ai": "0.3.0"
+    "@kernl-sdk/ai": "0.3.1"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/agent/base.ts

@@ -0,0 +1,220 @@
+import { randomID } from "@kernl-sdk/shared/lib";
+
+import type { Context, UnknownContext } from "@/context";
+import type { Tool, BaseToolkit } from "@/tool";
+import { memory } from "@/tool";
+import { MisconfiguredError } from "@/lib/error";
+import { AgentHooks } from "@/lifecycle";
+import type { Kernl } from "@/kernl";
+import type {
+  AgentMemoryCreate,
+  AgentMemoryUpdate,
+  MemoryListOptions,
+  MemorySearchQuery,
+} from "@/memory";
+
+import type { AgentKind, AgentMemoryConfig, AgentOutputType } from "./types";
+import type { TextOutput } from "@/thread/types";
+
+/**
+ * Base configuration shared by all agent types.
+ */
+export interface BaseAgentConfig<TContext = UnknownContext> {
+  id: string;
+  name: string;
+  description?: string;
+  instructions:
+    | string
+    | ((context: Context<TContext>) => Promise<string> | string);
+  toolkits?: BaseToolkit<TContext>[];
+  memory?: AgentMemoryConfig;
+}
+
+/**
+ * Common model interface shared by all model types.
+ */
+export interface BaseModel {
+  readonly provider: string;
+  readonly modelId: string;
+}
+
+/**
+ * Abstract base class for all agent types.
+ *
+ * Provides common functionality shared between text-based agents (Agent)
+ * and realtime agents (RealtimeAgent).
+ */
+export abstract class BaseAgent<
+  TContext = UnknownContext,
+  TOutput extends AgentOutputType = TextOutput,
+> extends AgentHooks<TContext, TOutput> {
+  protected kernl?: Kernl;
+
+  abstract readonly kind: AgentKind;
+  abstract readonly model: BaseModel;
+
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly instructions: (
+    context: Context<TContext>,
+  ) => Promise<string> | string;
+  readonly toolkits: BaseToolkit<TContext>[];
+  readonly systools: BaseToolkit<TContext>[];
+  readonly memory: AgentMemoryConfig;
+
+  constructor(config: BaseAgentConfig<TContext>) {
+    super();
+
+    if (config.id.trim() === "") {
+      throw new MisconfiguredError("Agent must have an id.");
+    }
+
+    this.id = config.id;
+    this.name = config.name;
+    this.description = config.description;
+    this.instructions =
+      typeof config.instructions === "function"
+        ? config.instructions
+        : () => config.instructions as string;
+    this.toolkits = config.toolkits ?? [];
+    this.systools = [];
+    this.memory = config.memory ?? { enabled: false };
+
+    for (const toolkit of this.toolkits) {
+      toolkit.bind(this);
+    }
+  }
+
+  /**
+   * Bind this agent to a kernl instance. Called by kernl.register().
+   */
+  bind(kernl: Kernl): void {
+    this.kernl = kernl;
+
+    // initialize system toolkits
+    if (this.memory.enabled) {
+      // safety: system tools only rely on ctx.agent, not ctx.context
+      const toolkit = memory as unknown as BaseToolkit<TContext>;
+      this.systools.push(toolkit);
+      toolkit.bind(this);
+    }
+  }
+
+  /**
+   * Get a specific tool by ID from systools and toolkits.
+   */
+  tool(id: string): Tool<TContext> | undefined {
+    // check systools first
+    for (const toolkit of this.systools) {
+      const tool = toolkit.get(id);
+      if (tool) return tool;
+    }
+    // then user toolkits
+    for (const toolkit of this.toolkits) {
+      const tool = toolkit.get(id);
+      if (tool) return tool;
+    }
+    return undefined;
+  }
+
+  /**
+   * Get all tools available from systools and toolkits for the given context.
+   */
+  async tools(context: Context<TContext>): Promise<Tool<TContext>[]> {
+    const all: Tool<TContext>[] = [];
+
+    for (const toolkit of [...this.systools, ...this.toolkits]) {
+      all.push(...(await toolkit.list(context)));
+    }
+
+    const ids = all.map((t) => t.id);
+    const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
+
+    if (duplicates.length > 0) {
+      throw new MisconfiguredError(
+        `Duplicate tool IDs found: ${[...new Set(duplicates)].join(", ")}`,
+      );
+    }
+
+    return all;
+  }
+
+  /**
+   * Memory management scoped to this agent.
+   */
+  get memories() {
+    if (!this.kernl) {
+      throw new MisconfiguredError(
+        `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
+      );
+    }
+
+    const agentId = this.id;
+    const kmem = this.kernl.memories;
+
+    return {
+      list: (
+        params?: Omit<MemoryListOptions, "filter"> & {
+          collection?: string;
+          limit?: number;
+        },
+      ) =>
+        kmem.list({
+          filter: {
+            scope: { agentId },
+            collections: params?.collection ? [params.collection] : undefined,
+          },
+          limit: params?.limit,
+        }),
+
+      create: (params: AgentMemoryCreate) =>
+        kmem.create({
+          id: params.id ?? `mem_${randomID()}`,
+          scope: {
+            namespace: params.namespace,
+            entityId: params.entityId,
+            agentId,
+          },
+          kind: "semantic",
+          collection: params.collection,
+          content: params.content,
+          wmem: params.wmem,
+          smem: params.smem,
+          timestamp: params.timestamp,
+          metadata: params.metadata,
+        }),
+
+      update: (params: AgentMemoryUpdate) =>
+        kmem.update({
+          id: params.id,
+          content: params.content,
+          collection: params.collection,
+          wmem: params.wmem,
+          smem: params.smem,
+          metadata: params.metadata,
+        }),
+
+      search: (
+        params: Omit<MemorySearchQuery, "filter"> & {
+          filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
+            scope?: Omit<
+              NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>,
+              "agentId"
+            >;
+          };
+        },
+      ) =>
+        kmem.search({
+          ...params,
+          filter: {
+            ...params.filter,
+            scope: {
+              ...params.filter?.scope,
+              agentId,
+            },
+          },
+        }),
+    };
+  }
+}

package/src/agent/index.ts

@@ -0,0 +1,2 @@
+export * from "./base";
+export * from "./types";

package/src/agent/types.ts

@@ -163,3 +163,8 @@ export interface AgentMemoryConfig {
    */
   enabled: boolean;
 }
+
+/**
+ * Agent kind discriminator.
+ */
+export type AgentKind = "llm" | "realtime";

package/src/agent.ts

@@ -6,7 +6,6 @@ import {
 } from "@kernl-sdk/protocol";
 
 import { Thread } from "./thread";
-import type { Kernl } from "./kernl";
 import type {
   RThreadsListParams,
   RThreadCreateParams,
@@ -15,30 +14,16 @@ import type {
   RThreadUpdateParams,
 } from "@/api/resources/threads/types";
 import type { Context, UnknownContext } from "./context";
-import { Tool, memory } from "./tool";
-import { BaseToolkit } from "./tool/toolkit";
 import {
   InputGuardrail,
   OutputGuardrail,
   type ResolvedAgentResponse,
 } from "./guardrail";
-import { AgentHooks } from "./lifecycle";
-import type {
-  AgentMemoryCreate,
-  AgentMemoryUpdate,
-  MemoryListOptions,
-  MemorySearchQuery,
-} from "./memory";
+import { BaseAgent } from "./agent/base";
 
-import { randomID } from "@kernl-sdk/shared/lib";
 import { MisconfiguredError, RuntimeError } from "./lib/error";
 
-/* types */
-import type {
-  AgentConfig,
-  AgentMemoryConfig,
-  AgentOutputType,
-} from "./agent/types";
+import type { AgentConfig, AgentOutputType } from "./agent/types";
 import type {
   TextOutput,
   ThreadExecuteOptions,
@@ -50,74 +35,30 @@ export class Agent<
     TContext = UnknownContext,
     TOutput extends AgentOutputType = TextOutput,
   >
-  extends AgentHooks<TContext, TOutput>
+  extends BaseAgent<TContext, TOutput>
   implements AgentConfig<TContext, TOutput>
 {
-  private kernl?: Kernl;
-
-  id: string;
-  name: string;
-  description?: string;
-  instructions: (context: Context<TContext>) => Promise<string> | string;
+  readonly kind = "llm";
+  readonly model: LanguageModel;
+  readonly modelSettings: LanguageModelRequestSettings;
 
-  model: LanguageModel;
-  modelSettings: LanguageModelRequestSettings;
-  // actions: ActionSet; /* TODO */
-  toolkits: BaseToolkit<TContext>[];
-  systools: BaseToolkit<TContext>[];
-  memory: AgentMemoryConfig;
-
-  guardrails: {
+  readonly guardrails: {
     input: InputGuardrail[];
     output: OutputGuardrail<AgentOutputType>[];
   };
-  output: TOutput = "text" as TOutput;
-  resetToolChoice: boolean;
+  readonly output: TOutput = "text" as TOutput;
+  readonly resetToolChoice: boolean;
 
   constructor(config: AgentConfig<TContext, TOutput>) {
-    super();
-    if (config.id.trim() === "") {
-      throw new MisconfiguredError("Agent must have an id.");
-    }
-    this.id = config.id;
-    this.name = config.name;
-    this.description = config.description;
-    this.instructions =
-      typeof config.instructions === "function"
-        ? config.instructions
-        : () => config.instructions as string;
-    this.model = config.model; // (TODO): include optional default setting for convenience like env.DEFAULT_LLM = "gpt-5"
-    this.modelSettings = config.modelSettings ?? {};
-
-    this.toolkits = config.toolkits ?? [];
-    this.systools = [];
-    this.memory = config.memory ?? { enabled: false };
-
-    for (const toolkit of this.toolkits) {
-      toolkit.bind(this);
-    }
+    super(config);
 
+    this.model = config.model;
+    this.modelSettings = config.modelSettings ?? {};
     this.guardrails = config.guardrails ?? { input: [], output: [] };
     if (config.output) {
       this.output = config.output;
     }
     this.resetToolChoice = config.resetToolChoice ?? true;
-    // this.toolUseBehavior = config.toolUseBehavior ?? "run_llm_again";
-  }
-
-  /**
-   * Bind this agent to a kernl instance. Called by kernl.register().
-   */
-  bind(kernl: Kernl): void {
-    this.kernl = kernl;
-
-    // initialize system toolkits
-    if (this.memory.enabled) {
-      // safety: system tools only rely on ctx.agent, not ctx.context
-      const toolkit = memory as unknown as BaseToolkit<TContext>;
-      this.systools.push(toolkit);
-      toolkit.bind(this);
-    }
   }
 
   /**
@@ -241,60 +182,6 @@ export class Agent<
     yield* this.kernl.scheduleStream(thread);
   }
 
-  /**
-   * @internal
-   *
-   * Get a specific tool by ID from systools and toolkits.
-   *
-   * @param id The tool ID to look up
-   * @returns The tool if found, undefined otherwise
-   */
-  tool(id: string): Tool<TContext> | undefined {
-    // Check systools first
-    for (const toolkit of this.systools) {
-      const tool = toolkit.get(id);
-      if (tool) return tool;
-    }
-    // Then user toolkits
-    for (const toolkit of this.toolkits) {
-      const tool = toolkit.get(id);
-      if (tool) return tool;
-    }
-    return undefined;
-  }
-
-  /**
-   * @internal
-   *
-   * Get all tools available from systools and toolkits for the given context.
-   * Checks for duplicate tool IDs across toolkits and throws an error if found.
-   *
-   * (TODO): Consider returning toolkits alongside tools so we can serialize them
-   * together and give agents more options for dealing with tool groups.
-   *
-   * @param context The context to use for filtering tools
-   * @returns Array of all available tools
-   * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
-   */
-  async tools(context: Context<TContext>): Promise<Tool<TContext>[]> {
-    const all: Tool<TContext>[] = [];
-
-    for (const toolkit of [...this.systools, ...this.toolkits]) {
-      all.push(...(await toolkit.list(context)));
-    }
-
-    const ids = all.map((t) => t.id);
-    const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
-
-    if (duplicates.length > 0) {
-      throw new MisconfiguredError(
-        `Duplicate tool IDs found: ${[...new Set(duplicates)].join(", ")}`,
-      );
-    }
-
-    return all;
-  }
-
   /**
    * Thread management scoped to this agent.
    *
@@ -331,110 +218,4 @@ export class Agent<
         kthreads.update(tid, patch),
     };
   }
-
-  /**
-   * Memory management scoped to this agent.
-   *
-   * Provides a simplified API for creating memories with:
-   * - Auto-generated IDs
-   * - Flattened scope fields (namespace, entityId) - agentId is implicit
-   * - Default kind of "semantic"
-   *
-   * @example
-   * ```ts
-   * await agent.memories.create({
-   *   namespace: "user-123",
-   *   collection: "preferences",
-   *   content: { text: "User prefers TypeScript" },
-   * });
-   * ```
-   */
-  get memories() {
-    if (!this.kernl) {
-      throw new MisconfiguredError(
-        `Agent ${this.id} not bound to kernl. Call kernl.register(agent) first.`,
-      );
-    }
-
-    const agentId = this.id;
-    const kmem = this.kernl.memories;
-
-    return {
-      /**
-       * List memories scoped to this agent.
-       */
-      list: (
-        params?: Omit<MemoryListOptions, "filter"> & {
-          collection?: string;
-          limit?: number;
-          // (TODO): we might want to add the filter back here
-        },
-      ) =>
-        kmem.list({
-          filter: {
-            scope: { agentId },
-            collections: params?.collection ? [params.collection] : undefined,
-          },
-          limit: params?.limit,
-        }),
-
-      /**
-       * Create a new memory scoped to this agent.
-       */
-      create: (params: AgentMemoryCreate) =>
-        kmem.create({
-          id: params.id ?? `mem_${randomID()}`,
-          scope: {
-            namespace: params.namespace,
-            entityId: params.entityId,
-            agentId,
-          },
-          kind: "semantic",
-          collection: params.collection,
-          content: params.content,
-          wmem: params.wmem,
-          smem: params.smem,
-          timestamp: params.timestamp,
-          metadata: params.metadata,
-        }),
-
-      /**
-       * Update an existing memory scoped to this agent.
-       */
-      update: (params: AgentMemoryUpdate) =>
-        kmem.update({
-          id: params.id,
-          content: params.content,
-          collection: params.collection,
-          wmem: params.wmem,
-          smem: params.smem,
-          metadata: params.metadata,
-        }),
-
-      /**
-       * Search memories scoped to this agent.
-       */
-      search: (
-        params: Omit<MemorySearchQuery, "filter"> & {
-          // (TODO): is this correct?
-          filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
-            scope?: Omit<
-              NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>,
-              "agentId"
-            >;
-          };
-        },
-      ) =>
-        kmem.search({
-          ...params,
-          filter: {
-            ...params.filter,
-            scope: {
-              ...params.filter?.scope,
-              agentId,
-            },
-          },
-        }),
-    };
-  }
 }