kernl 0.6.3 → 0.7.0

package/dist/memory/memory.js

@@ -71,6 +71,12 @@ export class Memory {
             topK: q.limit ?? 20,
         });
     }
+    /**
+     * List memories matching the filter.
+     */
+    async list(options) {
+        return this.store.list(options);
+    }
     /**
      * Repair indexing for a memory without modifying the DB row.
      */

package/dist/thread/thread.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/thread/thread.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EAML,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,WAAW,EACX,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAUvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,MAAM,CACjB,QAAQ,GAAG,OAAO,EAClB,SAAS,SAAS,iBAAiB,GAAG,MAAM;IAE5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAIlD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAwE;IAEvF,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAC,CAAc;gBAElB,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC;IA+BvD;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CACtD;IAoBD;;OAEG;IACI,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAuBjD;;;;;OAKG;YACY,QAAQ;IAgEvB;;;;;OAKG;YACY,IAAI;IA8BnB;;;;;OAKG;YACW,UAAU;IAuCxB;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,KAAK,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE;IAiBnD;;OAEG;IACH,MAAM;IAQN;;OAEG;YACW,cAAc;IAyC5B;;;;OAIG;YACW,YAAY;IA2C1B;;OAEG;YACW,mBAAmB;CA2ClC"}
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/thread/thread.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EAML,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,WAAW,EACX,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAUvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,MAAM,CACjB,QAAQ,GAAG,OAAO,EAClB,SAAS,SAAS,iBAAiB,GAAG,MAAM;IAE5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAIlD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAwE;IAEvF,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAC,CAAc;gBAElB,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC;IAgCvD;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CACtD;IAoBD;;OAEG;IACI,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAuBjD;;;;;OAKG;YACY,QAAQ;IAgEvB;;;;;OAKG;YACY,IAAI;IA8BnB;;;;;OAKG;YACW,UAAU;IAuCxB;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,KAAK,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE;IAiBnD;;OAEG;IACH,MAAM;IAQN;;OAEG;YACW,cAAc;IAyC5B;;;;OAIG;YACW,YAAY;IA4C1B;;OAEG;YACW,mBAAmB;CA2ClC"}

package/dist/thread/thread.js

@@ -70,6 +70,7 @@ export class Thread {
         this.agent = options.agent;
         this.context =
             options.context ?? new Context(this.namespace, {});
+        this.context.agent = options.agent;
         this.parent = options.task ?? null;
         this.model = options.model ?? options.agent.model;
         this.storage = options.storage;
@@ -262,7 +263,7 @@ export class Thread {
             state: this.state,
             tick: this._tick,
             context: this.context,
-            metadata: this.metadata,
+            // no metadata - not owned by checkpoint
         });
     }
     /**
@@ -351,6 +352,7 @@ export class Thread {
                 // (TMP) - passing the approval status through the context until actions system
                 // is refined
                 const ctx = new Context(this.namespace, this.context.context);
+                ctx.agent = this.agent;
                 ctx.approve(call.callId); // mark this call as approved
                 const res = await tool.invoke(ctx, call.arguments, call.callId);
                 return {

package/dist/tool/index.d.ts

@@ -1,4 +1,5 @@
 export { BaseTool, FunctionTool, HostedTool, tool } from "./tool.js";
 export { BaseToolkit, Toolkit, FunctionToolkit, MCPToolkit } from "./toolkit.js";
 export type { Tool, ToolResult, FunctionToolkitConfig, MCPToolkitConfig, ToolkitFilter, ToolkitFilterContext, } from "./types.js";
+export { memory } from "./sys/index.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tool/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9E,YAAY,EACV,IAAI,EACJ,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tool/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9E,YAAY,EACV,IAAI,EACJ,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC"}

package/dist/tool/index.js

@@ -1,2 +1,4 @@
 export { BaseTool, FunctionTool, HostedTool, tool } from "./tool.js";
 export { BaseToolkit, Toolkit, FunctionToolkit, MCPToolkit } from "./toolkit.js";
+// --- system toolkits ---
+export { memory } from "./sys/index.js";

package/dist/tool/sys/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * System toolkits.
+ *
+ * These are internal toolkits that can be enabled via agent config flags.
+ */
+export { memory } from "./memory.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tool/sys/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tool/sys/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/tool/sys/index.js

@@ -0,0 +1,6 @@
+/**
+ * System toolkits.
+ *
+ * These are internal toolkits that can be enabled via agent config flags.
+ */
+export { memory } from "./memory.js";

package/dist/tool/sys/memory.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Memory system toolkit.
+ *
+ * Provides tools for agents to store and retrieve memories.
+ * Enabled via `memory: true` in agent config.
+ */
+import { Toolkit } from "../toolkit.js";
+/**
+ * Memory system toolkit.
+ *
+ * Provides memories.search, memories.create, and memories.list tools.
+ */
+export declare const memory: Toolkit<unknown>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/tool/sys/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/tool/sys/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAmGrC;;;;GAIG;AACH,eAAO,MAAM,MAAM,kBAIjB,CAAC"}

package/dist/tool/sys/memory.js

@@ -0,0 +1,103 @@
+/**
+ * Memory system toolkit.
+ *
+ * Provides tools for agents to store and retrieve memories.
+ * Enabled via `memory: true` in agent config.
+ */
+import assert from "assert";
+import { z } from "zod";
+import { tool } from "../tool.js";
+import { Toolkit } from "../toolkit.js";
+// --- Tools ---
+/**
+ * Search memories for relevant information using natural language.
+ */
+const search = tool({
+    id: "memories.search",
+    description: "Search your memories. " +
+        "Use this to recall facts, preferences, or context you've previously stored.",
+    parameters: z.object({
+        query: z.string().describe("Natural language search query"),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Max results (default: 10)"),
+    }),
+    execute: async (ctx, { query, limit }) => {
+        assert(ctx.agent, "ctx.agent required for memory tools");
+        const mems = await ctx.agent.memories.search({
+            query,
+            limit: limit ?? 10,
+        });
+        return mems.map((h) => ({
+            id: h.document?.id,
+            text: h.document?.text,
+            score: h.score,
+        }));
+    },
+});
+/**
+ * Store a new memory to persist across conversations.
+ */
+const create = tool({
+    id: "memories.create",
+    description: "Store a new memory. Use this to remember important facts, user preferences, " +
+        "or context that should persist across conversations.",
+    parameters: z.object({
+        content: z.string().describe("Text content to remember"),
+        collection: z
+            .string()
+            .optional()
+            .describe("Category for organizing memories (default: 'facts')"),
+    }),
+    execute: async (ctx, { content, collection }) => {
+        assert(ctx.agent, "ctx.agent required for memory tools");
+        const mem = await ctx.agent.memories.create({
+            collection: collection ?? "facts",
+            content: { text: content },
+        });
+        return { id: mem.id, stored: true };
+    },
+});
+/**
+ * List stored memories, optionally filtered by collection.
+ */
+const list = tool({
+    id: "memories.list",
+    description: "List your stored memories. Use this to see what you've remembered, " +
+        "optionally filtered by collection.",
+    parameters: z.object({
+        collection: z.string().optional().describe("Filter by collection name"),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Max results (default: 20)"),
+    }),
+    execute: async (ctx, { collection, limit }) => {
+        assert(ctx.agent, "ctx.agent required for memory tools");
+        const mems = await ctx.agent.memories.list({
+            collection,
+            limit: limit ?? 20,
+        });
+        return mems.map((r) => ({
+            id: r.id,
+            collection: r.collection,
+            text: r.content.text,
+        }));
+    },
+});
+// --- Toolkit ---
+/**
+ * Memory system toolkit.
+ *
+ * Provides memories.search, memories.create, and memories.list tools.
+ */
+export const memory = new Toolkit({
+    id: "sys.memory",
+    description: "Tools for storing and retrieving agent memories",
+    tools: [list, create, search],
+});

package/dist/tool/tool.d.ts

@@ -1,5 +1,5 @@
 import { Context, UnknownContext } from "../context.js";
-import type { LanguageModelTool } from "@kernl-sdk/protocol";
+import { type LanguageModelTool } from "@kernl-sdk/protocol";
 import type { ToolConfig, ToolApprovalFunction, ToolEnabledFunction, ToolErrorFunction, ToolInputParameters, ToolResult } from "./types.js";
 /**
  * Exposes a function to the agent as a tool to be called

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

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

package/dist/tool/tool.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
 import { ModelBehaviorError } from "../lib/error.js";
 import { logger } from "../lib/logger.js";
+import { FAILED, COMPLETED, INTERRUPTIBLE, } from "@kernl-sdk/protocol";
 import { json } from "@kernl-sdk/shared/lib";
-import { FAILED, COMPLETED, INTERRUPTIBLE } from "@kernl-sdk/protocol";
 /**
  * Exposes a function to the agent as a tool to be called
  *
@@ -122,7 +122,7 @@ export class FunctionTool extends BaseTool {
             description: this.description,
             parameters: z.toJSONSchema(this.parameters ?? z.object({}), {
                 target: "draft-7",
-            }), // Use empty object if no parameters (matches AI SDK)
+            }), // use empty object if no parameters (matches AI SDK)
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",

package/src/agent/__tests__/systools.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "vitest";
+import { Agent } from "@/agent";
+import { Kernl } from "@/kernl";
+import { Context } from "@/context";
+import { createMockModel } from "@/thread/__tests__/fixtures/mock-model";
+import { message } from "@kernl-sdk/protocol";
+
+describe("Agent systools", () => {
+  const model = createMockModel(async () => ({
+    content: [message({ role: "assistant", text: "Done" })],
+    finishReason: "stop",
+    usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 },
+    warnings: [],
+  }));
+
+  describe("memory toolkit", () => {
+    it("adds memory toolkit when memory.enabled is true", () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+        memory: { enabled: true },
+      });
+
+      const kernl = new Kernl();
+      kernl.register(agent);
+
+      expect(agent.systools.length).toBe(1);
+      expect(agent.systools[0].id).toBe("sys.memory");
+    });
+
+    it("has no systools when memory not configured", () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+      });
+
+      const kernl = new Kernl();
+      kernl.register(agent);
+
+      expect(agent.systools.length).toBe(0);
+    });
+
+    it("has no systools when memory.enabled is false", () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+        memory: { enabled: false },
+      });
+
+      const kernl = new Kernl();
+      kernl.register(agent);
+
+      expect(agent.systools.length).toBe(0);
+    });
+
+    it("can retrieve memory tools via agent.tool()", () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+        memory: { enabled: true },
+      });
+
+      const kernl = new Kernl();
+      kernl.register(agent);
+
+      expect(agent.tool("memories.search")).toBeDefined();
+      expect(agent.tool("memories.create")).toBeDefined();
+      expect(agent.tool("memories.list")).toBeDefined();
+    });
+
+    it("includes memory tools in agent.tools() output", async () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+        memory: { enabled: true },
+      });
+
+      const kernl = new Kernl();
+      kernl.register(agent);
+
+      const ctx = new Context("test");
+      const tools = await agent.tools(ctx);
+      const ids = tools.map((t) => t.id);
+
+      expect(ids).toContain("memories.search");
+      expect(ids).toContain("memories.create");
+      expect(ids).toContain("memories.list");
+    });
+
+    it("systools appear before user toolkits in tools() output", async () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+        memory: { enabled: true },
+      });
+
+      const kernl = new Kernl();
+      kernl.register(agent);
+
+      const ctx = new Context("test");
+      const tools = await agent.tools(ctx);
+
+      // Memory tools should be first (from systools)
+      expect(tools[0].id).toBe("memories.search");
+      expect(tools[1].id).toBe("memories.create");
+      expect(tools[2].id).toBe("memories.list");
+    });
+  });
+
+  describe("memory config defaults", () => {
+    it("defaults memory to { enabled: false }", () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+      });
+
+      expect(agent.memory).toEqual({ enabled: false });
+    });
+
+    it("preserves memory config when provided", () => {
+      const agent = new Agent({
+        id: "test-agent",
+        name: "Test",
+        instructions: "Test",
+        model,
+        memory: { enabled: true },
+      });
+
+      expect(agent.memory).toEqual({ enabled: true });
+    });
+  });
+});

package/src/agent/types.ts

@@ -23,6 +23,9 @@ export interface AgentConfig<
   /* The name of the agent (defaults to ID if not provided) */
   name: string;
 
+  /* A brief description of the agent's purpose */
+  description?: string;
+
   /**
    * The instructions for the agent. Will be used as the "system prompt" when this agent is
    * invoked. Describes what the agent should do, and how it responds.
@@ -85,6 +88,14 @@ export interface AgentConfig<
    */
   toolkits?: BaseToolkit<TContext>[];
 
+  /**
+   * Memory configuration for this agent.
+   * Enables memory system tools (memories.search, memories.create, memories.list).
+   *
+   * Requires kernl to be configured with memory storage.
+   */
+  memory?: AgentMemoryConfig;
+
   /**
    * A list of checks that run in parallel to the agent's execution on the input + output for the agent,
    * depending on the configuration.
@@ -146,3 +157,13 @@ export interface AgentGuardrails<
  * 'text' is a special type that indicates the output will be a string.
  */
 export type AgentResponseType = TextResponse | ZodType;
+
+/**
+ * Memory configuration for an agent.
+ */
+export interface AgentMemoryConfig {
+  /**
+   * Enable memory system tools for this agent.
+   */
+  enabled: boolean;
+}

package/src/agent.ts

@@ -15,7 +15,7 @@ import type {
   RThreadUpdateParams,
 } from "@/api/resources/threads/types";
 import type { Context, UnknownContext } from "./context";
-import { Tool } from "./tool";
+import { Tool, memory } from "./tool";
 import { BaseToolkit } from "./tool/toolkit";
 import {
   InputGuardrail,
@@ -23,17 +23,27 @@ import {
   type ResolvedAgentResponse,
 } from "./guardrail";
 import { AgentHooks } from "./lifecycle";
+import type {
+  AgentMemoryCreate,
+  MemoryListOptions,
+  MemorySearchQuery,
+} from "./memory";
 
+import { randomID } from "@kernl-sdk/shared/lib";
 import { MisconfiguredError, RuntimeError } from "./lib/error";
-import type { AgentConfig, AgentResponseType } from "@/agent/types";
+
+/* types */
+import type {
+  AgentConfig,
+  AgentMemoryConfig,
+  AgentResponseType,
+} from "./agent/types";
 import type {
   TextResponse,
   ThreadExecuteOptions,
   ThreadExecuteResult,
   ThreadStreamEvent,
-} from "@/thread/types";
-import type { AgentMemoryCreate, MemorySearchQuery } from "./memory";
-import { randomID } from "@kernl-sdk/shared/lib";
+} from "./thread/types";
 
 export class Agent<
     TContext = UnknownContext,
@@ -46,12 +56,15 @@ export class Agent<
 
   id: string;
   name: string;
+  description?: string;
   instructions: (context: Context<TContext>) => Promise<string> | string;
 
   model: LanguageModel;
   modelSettings: LanguageModelRequestSettings;
-  toolkits: BaseToolkit<TContext>[];
   // actions: ActionSet; /* TODO */
+  toolkits: BaseToolkit<TContext>[];
+  systools: BaseToolkit<TContext>[];
+  memory: AgentMemoryConfig;
 
   guardrails: {
     input: InputGuardrail[];
@@ -59,10 +72,9 @@ export class Agent<
   };
   responseType: TResponse = "text" as TResponse;
   resetToolChoice: boolean;
-  // toolUseBehavior: ToolUseBehavior; (TODO)
 
   // --- (TODO) ---
-  // handoffDescription: string; // ??
+  // toolUseBehavior: ToolUseBehavior;
   // handoffs: (Agent<any, TResponse> | Handoff<any, TResponse>)[];
   // ----------
 
@@ -81,6 +93,7 @@ export class Agent<
     }
     this.id = config.id;
     this.name = config.name;
+    this.description = config.description;
     this.instructions =
       typeof config.instructions === "function"
         ? config.instructions
@@ -89,6 +102,9 @@ export class Agent<
     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);
     }
@@ -99,21 +115,6 @@ export class Agent<
     }
     this.resetToolChoice = config.resetToolChoice ?? true;
     // this.toolUseBehavior = config.toolUseBehavior ?? "run_llm_again";
-
-    // this.handoffDescription = config.handoffDescription ?? "";
-    // this.handoffs = config.handoffs ?? [];
-
-    // --- Runtime warning for handoff response type compatibility ---
-    // if (config.handoffresponseTypeWarningEnabled) {
-    //     ...
-    //     if (responseTypes.size > 1) {
-    //       logger.warn(
-    //         `[Agent] Warning: Handoff agents have different response types: ${Array.from(responseTypes).join(", ")}.
-    //          You can make it type-safe by using Agent.create({ ... }) method instead.`,
-    //       );
-    //     }
-    //   }
-    // }
   }
 
   /**
@@ -121,6 +122,14 @@ export class Agent<
    */
   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);
+    }
   }
 
   /**
@@ -247,12 +256,18 @@ export class Agent<
   /**
    * @internal
    *
-   * Get a specific tool by ID from all toolkits.
+   * 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;
@@ -263,7 +278,7 @@ export class Agent<
   /**
    * @internal
    *
-   * Get all tools available from all toolkits for the given context.
+   * 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
@@ -274,24 +289,22 @@ export class Agent<
    * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
    */
   async tools(context: Context<TContext>): Promise<Tool<TContext>[]> {
-    const allTools: Tool<TContext>[] = [];
-    const toolIds = new Set<string>();
+    const all: Tool<TContext>[] = [];
 
-    for (const toolkit of this.toolkits) {
-      const tools = await toolkit.list(context);
+    for (const toolkit of [...this.systools, ...this.toolkits]) {
+      all.push(...(await toolkit.list(context)));
+    }
 
-      const duplicates = tools.map((t) => t.id).filter((id) => toolIds.has(id));
-      if (duplicates.length > 0) {
-        throw new MisconfiguredError(
-          `Duplicate tool IDs found across toolkits: ${duplicates.join(", ")}`,
-        );
-      }
+    const ids = all.map((t) => t.id);
+    const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
 
-      tools.forEach((t) => toolIds.add(t.id));
-      allTools.push(...tools);
+    if (duplicates.length > 0) {
+      throw new MisconfiguredError(
+        `Duplicate tool IDs found: ${[...new Set(duplicates)].join(", ")}`,
+      );
     }
 
-    return allTools;
+    return all;
   }
 
   /**
@@ -359,6 +372,24 @@ export class Agent<
     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.
        */
@@ -384,6 +415,7 @@ export class Agent<
        */
       search: (
         params: Omit<MemorySearchQuery, "filter"> & {
+          // (TODO): is this correct?
           filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
             scope?: Omit<
               NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>,