kernl 0.6.3 → 0.7.1

package/dist/memory/memory.d.ts

@@ -1,5 +1,5 @@
 import type { SearchHit } from "@kernl-sdk/retrieval";
-import type { NewMemory, MemoryRecord, MemoryRecordUpdate, MemoryScope, MemoryConfig, MemorySearchQuery, IndexMemoryRecord, WorkingMemorySnapshot, ShortTermMemorySnapshot, MemoryReindexParams } from "./types.js";
+import type { NewMemory, MemoryRecord, MemoryRecordUpdate, MemoryScope, MemoryConfig, MemorySearchQuery, MemoryListOptions, IndexMemoryRecord, WorkingMemorySnapshot, ShortTermMemorySnapshot, MemoryReindexParams } from "./types.js";
 /**
  * Memory is the primary memory abstraction for agents.
  *
@@ -35,6 +35,10 @@ export declare class Memory {
      * adapts based on backend capabilities (e.g. drops text for pgvector).
      */
     search(q: MemorySearchQuery): Promise<SearchHit<IndexMemoryRecord>[]>;
+    /**
+     * List memories matching the filter.
+     */
+    list(options?: MemoryListOptions): Promise<MemoryRecord[]>;
     /**
      * Repair indexing for a memory without modifying the DB row.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/memory/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAInE,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,iBAAiB,EAEjB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;GAWG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAEhE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAEzD,MAAM,EAAE,YAAY;IAShC;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAYtD;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAe/D;;;;;OAKG;IACG,MAAM,CAAC,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAc3E;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBzD;;OAEG;IACG,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAO3E;;OAEG;IACG,mBAAmB,CACvB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,uBAAuB,CAAC;CAMpC"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/memory/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAInE,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EAEjB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;GAWG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAEhE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAEzD,MAAM,EAAE,YAAY;IAShC;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IAYtD;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAe/D;;;;;OAKG;IACG,MAAM,CAAC,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAc3E;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAIhE;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBzD;;OAEG;IACG,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAO3E;;OAEG;IACG,mBAAmB,CACvB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,uBAAuB,CAAC;CAMpC"}

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.1",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -35,9 +35,9 @@
     "@modelcontextprotocol/sdk": "^1.20.2",
     "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"
+    "@kernl-sdk/protocol": "0.2.6",
+    "@kernl-sdk/shared": "^0.2.0",
+    "@kernl-sdk/retrieval": "0.1.1"
   },
   "devDependencies": {
     "@ai-sdk/openai": "3.0.0-beta.57",
@@ -45,7 +45,7 @@
     "tsc-alias": "^1.8.10",
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
-    "@kernl-sdk/ai": "0.2.7"
+    "@kernl-sdk/ai": "0.2.8"
   },
   "scripts": {
     "clean": "rm -rf dist",

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;
+}