kernl 0.6.2 → 0.7.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> kernl@0.6.1 build /Users/andjones/Documents/projects/kernl/packages/kernl
+> kernl@0.6.3 build /Users/andjones/Documents/projects/kernl/packages/kernl
 > tsc && tsc-alias --resolve-full-paths
 

package/.turbo/turbo-check-types.log

@@ -1,4 +1,4 @@
 
-> @kernl-sdk/core@0.2.2 check-types /Users/andjones/Documents/projects/kernl/packages/kernl
+> kernl@0.6.2 check-types /Users/andjones/Documents/projects/kernl/packages/kernl
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @kernl/core
 
+## 0.7.0
+
+### Minor Changes
+
+- 13545a5: Add memory system tools and agents public API
+  - Add system tools infrastructure (`agent.systools`) for built-in agent capabilities
+  - Add memory toolkit with `memories.search`, `memories.create`, `memories.list` tools
+  - Add `memory: { enabled: true }` agent config to enable memory tools
+  - Add `ctx.agent` reference for tools to access agent APIs
+  - Add `kernl.agents` public API with `get`, `list`, `has`, `unregister` methods
+  - Add `Memory.list()` method for listing memories with filters
+  - Add `agent.description` field for agent metadata
+  - Fix: exclude metadata from thread checkpoint to prevent race conditions
+
+## 0.6.3
+
+### Patch Changes
+
+- a7d6138: Add agent.memories API and memory integration with vector backends
+
+  **@kernl-sdk/retrieval**
+  - Add `planQuery()` for adapting queries based on backend capabilities
+  - Add `SearchCapabilities` interface to describe backend features
+  - Gracefully degrade hybrid queries when not supported
+
+  **@kernl-sdk/pg**
+  - Add `capabilities()` method to PGVectorSearchIndex
+  - Fix hit decoding to include id in document
+
+  **@kernl-sdk/turbopuffer**
+  - Add `capabilities()` method describing supported search modes
+  - Add bigint type mapping for timestamps
+  - Fix hit decoding to include id in document
+  - Add memory integration tests
+
+  **kernl**
+  - Add `agent.memories.create()` with simplified syntax (auto-generated IDs, flattened scope)
+  - Add `agent.memories.search()` scoped to agent
+  - Add backend-aware codecs for Turbopuffer field mapping (tvec → vector)
+  - Default `include: true` for Turbopuffer queries to return all attributes
+
+- Updated dependencies [a7d6138]
+  - @kernl-sdk/retrieval@0.1.0
+
 ## 0.6.2
 
 ### Patch Changes

package/dist/agent/__tests__/concurrency.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { Agent } from "../../agent.js";
-import { Kernl } from "../../kernl.js";
+import { Kernl } from "../../kernl/index.js";
 import { createMockModel } from "../../thread/__tests__/fixtures/mock-model.js";
 import { RuntimeError } from "../../lib/error.js";
 import { message } from "@kernl-sdk/protocol";

package/dist/agent/__tests__/run.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import { Agent } from "../../agent.js";
-import { Kernl } from "../../kernl.js";
+import { Kernl } from "../../kernl/index.js";
 import { createMockModel } from "../../thread/__tests__/fixtures/mock-model.js";
 import { MisconfiguredError } from "../../lib/error.js";
 import { message } from "@kernl-sdk/protocol";

package/dist/agent/__tests__/systools.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=systools.test.d.ts.map

package/dist/agent/__tests__/systools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"systools.test.d.ts","sourceRoot":"","sources":["../../../src/agent/__tests__/systools.test.ts"],"names":[],"mappings":""}

package/dist/agent/__tests__/systools.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect } from "vitest";
+import { Agent } from "../../agent.js";
+import { Kernl } from "../../kernl/index.js";
+import { Context } from "../../context.js";
+import { createMockModel } from "../../thread/__tests__/fixtures/mock-model.js";
+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/dist/{types/agent.d.ts → agent/types.d.ts}

@@ -3,13 +3,14 @@ import { Context, UnknownContext } from "../context.js";
 import { LanguageModel, LanguageModelRequestSettings } from "@kernl-sdk/protocol";
 import { InputGuardrail, OutputGuardrail } from "../guardrail.js";
 import { BaseToolkit } from "../tool/index.js";
-import { TextResponse } from "./thread.js";
+import { TextResponse } from "../thread/types.js";
 /**
  * Configuration for an agent.
  */
 export interface AgentConfig<TContext = UnknownContext, TResponse extends AgentResponseType = TextResponse> {
     id: string;
     name: string;
+    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.
@@ -53,6 +54,13 @@ export interface AgentConfig<TContext = UnknownContext, TResponse extends AgentR
      * ```
      */
     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.
@@ -88,4 +96,13 @@ export interface AgentGuardrails<TResponse extends AgentResponseType = TextRespo
  * 'text' is a special type that indicates the output will be a string.
  */
 export type AgentResponseType = TextResponse | ZodType;
-//# sourceMappingURL=agent.d.ts.map
+/**
+ * Memory configuration for an agent.
+ */
+export interface AgentMemoryConfig {
+    /**
+     * Enable memory system tools for this agent.
+     */
+    enabled: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,aAAa,EACb,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAGlD,EAAE,EAAE,MAAM,CAAC;IAGX,IAAI,EAAE,MAAM,CAAC;IAGb,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;OAOG;IACH,YAAY,EACR,MAAM,GACN,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;IAe/D;;;;OAIG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,4BAA4B,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IAsBzB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,SAAS,SAAS,iBAAiB,GAAG,YAAY;IAElD;;;OAGG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB;;;OAGG;IACH,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,OAAO,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/agent.d.ts

@@ -1,21 +1,25 @@
 import { LanguageModel, LanguageModelItem, LanguageModelRequestSettings } from "@kernl-sdk/protocol";
-import type { Kernl } from "./kernl.js";
+import type { Kernl } from "./kernl/index.js";
 import type { RThreadsListParams, RThreadCreateParams, RThreadGetOptions, RThreadHistoryParams, RThreadUpdateParams } from "./api/resources/threads/types.js";
 import type { Context, UnknownContext } from "./context.js";
 import { Tool } from "./tool/index.js";
 import { BaseToolkit } from "./tool/toolkit.js";
 import { InputGuardrail, OutputGuardrail, type ResolvedAgentResponse } from "./guardrail.js";
 import { AgentHooks } from "./lifecycle.js";
-import type { AgentConfig, AgentResponseType } from "./types/agent.js";
-import type { TextResponse, ThreadExecuteOptions, ThreadExecuteResult, ThreadStreamEvent } from "./types/thread.js";
+import type { AgentConfig, AgentMemoryConfig, AgentResponseType } from "./agent/types.js";
+import type { TextResponse, ThreadExecuteOptions, ThreadExecuteResult, ThreadStreamEvent } from "./thread/types.js";
+import type { AgentMemoryCreate, MemoryListOptions, MemorySearchQuery } from "./memory/index.js";
 export declare class Agent<TContext = UnknownContext, TResponse extends AgentResponseType = TextResponse> extends AgentHooks<TContext, TResponse> implements AgentConfig<TContext, TResponse> {
     private kernl?;
     id: string;
     name: string;
+    description?: string;
     instructions: (context: Context<TContext>) => Promise<string> | string;
     model: LanguageModel;
     modelSettings: LanguageModelRequestSettings;
     toolkits: BaseToolkit<TContext>[];
+    systools: BaseToolkit<TContext>[];
+    memory: AgentMemoryConfig;
     guardrails: {
         input: InputGuardrail[];
         output: OutputGuardrail<AgentResponseType>[];
@@ -46,7 +50,7 @@ export declare class Agent<TContext = UnknownContext, TResponse extends AgentRes
     /**
      * @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
@@ -55,7 +59,7 @@ export declare class Agent<TContext = UnknownContext, TResponse extends AgentRes
     /**
      * @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
@@ -73,11 +77,49 @@ export declare class Agent<TContext = UnknownContext, TResponse extends AgentRes
      */
     get threads(): {
         get: (tid: string, options?: RThreadGetOptions) => Promise<import("./index.js").Thread | null>;
-        list: (params?: Omit<RThreadsListParams, "agentId">) => Promise<import("./api/pagination/cursor.js").CursorPage<import("./index.js").Thread, RThreadsListParams>>;
+        list: (params?: Omit<RThreadsListParams, "agentId">) => Promise<import("@kernl-sdk/shared").CursorPage<import("./index.js").Thread, RThreadsListParams>>;
         delete: (tid: string) => Promise<void>;
         history: (tid: string, params?: RThreadHistoryParams) => Promise<import("./index.js").ThreadEvent[]>;
         create: (params: Omit<RThreadCreateParams, "agentId" | "model">) => Promise<import("./index.js").Thread>;
         update: (tid: string, patch: RThreadUpdateParams) => Promise<import("./index.js").Thread | null>;
     };
+    /**
+     * 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(): {
+        /**
+         * List memories scoped to this agent.
+         */
+        list: (params?: Omit<MemoryListOptions, "filter"> & {
+            collection?: string;
+            limit?: number;
+        }) => Promise<import("./memory/index.js").MemoryRecord[]>;
+        /**
+         * Create a new memory scoped to this agent.
+         */
+        create: (params: AgentMemoryCreate) => Promise<import("./memory/index.js").MemoryRecord>;
+        /**
+         * Search memories scoped to this agent.
+         */
+        search: (params: Omit<MemorySearchQuery, "filter"> & {
+            filter?: Omit<NonNullable<MemorySearchQuery["filter"]>, "scope"> & {
+                scope?: Omit<NonNullable<NonNullable<MemorySearchQuery["filter"]>["scope"]>, "agentId">;
+            };
+        }) => Promise<import("@kernl-sdk/retrieval").SearchHit<import("./memory/index.js").IndexMemoryRecord>[]>;
+    };
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EACb,iBAAiB,EACjB,4BAA4B,EAC7B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,KAAK,CACd,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY,CAEpD,SAAQ,UAAU,CAAC,QAAQ,EAAE,SAAS,CACtC,YAAW,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC;IAE3C,OAAO,CAAC,KAAK,CAAC,CAAQ;IAEtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAEvE,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IAGlC,UAAU,EAAE;QACV,KAAK,EAAE,cAAc,EAAE,CAAC;QACxB,MAAM,EAAE,eAAe,CAAC,iBAAiB,CAAC,EAAE,CAAC;KAC9C,CAAC;IACF,YAAY,EAAE,SAAS,CAAuB;IAC9C,eAAe,EAAE,OAAO,CAAC;gBAgBb,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC;IA0CpD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIxB;;;;;OAKG;IACG,GAAG,CACP,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,OAAO,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CAAC;IAkDjE;;;;;;;OAOG;IACI,MAAM,CACX,KAAK,EAAE,MAAM,GAAG,iBAAiB,EAAE,EACnC,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACvC,aAAa,CAAC,iBAAiB,CAAC;IAmDnC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,SAAS;IAQ5C;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAqBlE;;;;OAIG;IACH,IAAI,OAAO;mBAWI,MAAM,YAAY,iBAAiB;wBAE/B,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC;sBAEpC,MAAM;uBACL,MAAM,WAAW,oBAAoB;yBAEnC,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,OAAO,CAAC;sBASjD,MAAM,SAAS,mBAAmB;MAGnD;CACF"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -1,15 +1,20 @@
 import { message, } from "@kernl-sdk/protocol";
 import { Thread } from "./thread/index.js";
+import { memory } from "./tool/index.js";
 import { AgentHooks } from "./lifecycle.js";
 import { MisconfiguredError, RuntimeError } from "./lib/error.js";
+import { randomID } from "@kernl-sdk/shared/lib";
 export class Agent extends AgentHooks {
     kernl;
     id;
     name;
+    description;
     instructions;
     model;
     modelSettings;
     toolkits;
+    systools;
+    memory;
     // actions: ActionSet; /* TODO */
     guardrails;
     responseType = "text";
@@ -33,6 +38,7 @@ export class Agent extends AgentHooks {
         }
         this.id = config.id;
         this.name = config.name;
+        this.description = config.description;
         this.instructions =
             typeof config.instructions === "function"
                 ? config.instructions
@@ -40,6 +46,8 @@ export class Agent extends AgentHooks {
         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);
         }
@@ -68,6 +76,13 @@ export class Agent extends AgentHooks {
      */
     bind(kernl) {
         this.kernl = kernl;
+        // initialize system toolkits
+        if (this.memory.enabled) {
+            // safety: system tools only rely on ctx.agent, not ctx.context
+            const toolkit = memory;
+            this.systools.push(toolkit);
+            toolkit.bind(this);
+        }
     }
     /**
      * Blocking execution - spawns or resumes thread and waits for completion
@@ -167,12 +182,19 @@ export class Agent extends AgentHooks {
     /**
      * @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) {
+        // 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)
@@ -183,7 +205,7 @@ export class Agent extends AgentHooks {
     /**
      * @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
@@ -194,18 +216,16 @@ export class Agent extends AgentHooks {
      * @throws {MisconfiguredError} If duplicate tool IDs are found across toolkits
      */
     async tools(context) {
-        const allTools = [];
-        const toolIds = new Set();
-        for (const toolkit of this.toolkits) {
-            const tools = 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(", ")}`);
-            }
-            tools.forEach((t) => toolIds.add(t.id));
-            allTools.push(...tools);
+        const all = [];
+        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 allTools;
+        return all;
     }
     /**
      * Thread management scoped to this agent.
@@ -234,4 +254,71 @@ export class Agent extends AgentHooks {
             update: (tid, patch) => 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) => kmem.list({
+                filter: {
+                    scope: { agentId },
+                    collections: params?.collection ? [params.collection] : undefined,
+                },
+                limit: params?.limit,
+            }),
+            /**
+             * Create a new memory scoped to this agent.
+             */
+            create: (params) => 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) => kmem.search({
+                ...params,
+                filter: {
+                    ...params.filter,
+                    scope: {
+                        ...params.filter?.scope,
+                        agentId,
+                    },
+                },
+            }),
+        };
+    }
 }

package/dist/api/models/thread.d.ts

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

package/dist/api/resources/agents/agents.d.ts

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

package/dist/api/resources/agents/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../../../src/api/resources/agents/agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;GAMG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAEzD;;;;;OAKG;IACH,GAAG,CACD,QAAQ,GAAG,cAAc,EACzB,SAAS,SAAS,iBAAiB,GAAG,YAAY,EAClD,EAAE,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,SAAS;IAKrD;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;;;;OAKG;IACH,IAAI,IAAI,KAAK,CAAC,cAAc,EAAE,iBAAiB,CAAC,EAAE;IAOlD;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAGhC"}

package/dist/api/resources/agents/agents.js

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

package/dist/api/resources/agents/index.d.ts

@@ -0,0 +1,2 @@
+export { RAgents } from "./agents.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/resources/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/resources/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC"}

package/dist/api/resources/agents/index.js

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