kernl 0.6.2 → 0.7.0

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":"AACA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAKpD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EAEnB,iBAAiB,EAGjB,mBAAmB,EACnB,UAAU,EACX,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,wBAAgB,IAAI,CAClB,QAAQ,GAAG,cAAc,EACzB,WAAW,SAAS,mBAAmB,GAAG,SAAS,EACnD,OAAO,GAAG,MAAM,EAEhB,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,GACjD,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,CAE9C;AAED;;GAEG;AACH,8BAAsB,QAAQ,CAAC,QAAQ,GAAG,cAAc;IACtD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,CAAC,GAAG,CAAC,CAAC;IAErD;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAE5E;;OAEG;IACH,QAAQ,CAAC,SAAS,IAAI,iBAAiB;CACxC;AAED;;GAEG;AACH,qBAAa,YAAY,CACvB,QAAQ,GAAG,cAAc,EACzB,WAAW,SAAS,mBAAmB,GAAG,SAAS,EACnD,OAAO,GAAG,OAAO,CACjB,SAAQ,QAAQ,CAAC,QAAQ,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,OAAO,CAAC,OAAO,CAAsD;IAErE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,gBAAgB,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACpD,SAAS,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;gBAE7B,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC;IAqC9D;;;;OAIG;IACG,MAAM,CACV,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAgB/B;;OAEG;YACW,OAAO;IAuCrB;;OAEG;IACH,SAAS,IAAI,iBAAiB;CAU/B;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACtC,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAU;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE5C;;OAEG;IACH,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAA4B;IAE7D;;OAEG;IACH,gBAAgB,EAAE,oBAAoB,CAAC,GAAG,CAAC,CAAqB;gBAEpD,MAAM,EAAE;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KACpC;IAOD;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;OAEG;IACH,SAAS,IAAI,iBAAiB;CAQ/B"}

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.2",
+  "version": "0.7.0",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -36,6 +36,7 @@
     "pino": "^9.6.0",
     "zod": "^4.1.12",
     "@kernl-sdk/protocol": "0.2.5",
+    "@kernl-sdk/retrieval": "0.1.0",
     "@kernl-sdk/shared": "^0.1.6"
   },
   "devDependencies": {
@@ -44,9 +45,10 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/ai": "0.2.6"
+    "@kernl-sdk/ai": "0.2.7"
   },
   "scripts": {
+    "clean": "rm -rf dist",
     "build": "tsc && tsc-alias --resolve-full-paths",
     "dev": "tsc --watch",
     "lint": "eslint src/",

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/{types/agent.ts → agent/types.ts}

@@ -8,7 +8,7 @@ import {
 import { InputGuardrail, OutputGuardrail } from "@/guardrail";
 import { BaseToolkit } from "@/tool";
 
-import { TextResponse } from "./thread";
+import { TextResponse } from "@/thread/types";
 
 /**
  * Configuration for an agent.
@@ -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,15 +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 "./types/agent";
+
+/* types */
+import type {
+  AgentConfig,
+  AgentMemoryConfig,
+  AgentResponseType,
+} from "./agent/types";
 import type {
   TextResponse,
   ThreadExecuteOptions,
   ThreadExecuteResult,
   ThreadStreamEvent,
-} from "./types/thread";
+} from "./thread/types";
 
 export class Agent<
     TContext = UnknownContext,
@@ -44,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[];
@@ -57,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>)[];
   // ----------
 
@@ -79,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
@@ -87,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);
     }
@@ -97,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.`,
-    //       );
-    //     }
-    //   }
-    // }
   }
 
   /**
@@ -119,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);
+    }
   }
 
   /**
@@ -245,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;
@@ -261,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
@@ -272,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;
   }
 
   /**
@@ -328,4 +343,97 @@ 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,
+        }),
+
+      /**
+       * 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,
+            },
+          },
+        }),
+    };
+  }
 }

package/src/api/__tests__/threads.test.ts

@@ -4,10 +4,10 @@ import { message, RUNNING } from "@kernl-sdk/protocol";
 
 import { Agent } from "@/agent";
 import { InMemoryThreadStore } from "@/storage/in-memory";
-import type { AgentRegistry, ModelRegistry } from "@/types/kernl";
+import type { AgentRegistry, ModelRegistry } from "@/kernl/types";
 import type { NewThread } from "@/storage";
 import { tevent } from "@/thread/utils";
-import type { ThreadEvent } from "@/types/thread";
+import type { ThreadEvent } from "@/thread/types";
 import { RThreads } from "@/api/resources/threads";
 import type { MThread } from "@/api/models";