kernl 0.6.2 → 0.7.0

package/src/memory/types.ts

@@ -0,0 +1,282 @@
+/**
+ * Memory types.
+ */
+
+import type { JSONObject } from "@kernl-sdk/protocol";
+import type { AsyncCodec } from "@kernl-sdk/shared/lib";
+import type { IndexHandle } from "@kernl-sdk/retrieval";
+
+import type { MemoryStore } from "./store";
+
+// -------------------
+// Byte types
+// -------------------
+
+export type TextByte = string;
+
+/**
+ * Image content.
+ *
+ * NOTE: Parallels @kernl-sdk/protocol's FilePart type.
+ * @see packages/protocol/src/language-model/item.ts
+ */
+export interface ImageByte {
+  data: Uint8Array | string; // raw bytes or base64/URI
+  mime: string; // "image/png", "image/jpeg", etc.
+  alt?: string; // alt text / description
+}
+
+/**
+ * Audio content.
+ */
+export interface AudioByte {
+  data: Uint8Array | string;
+  mime: string; // "audio/wav", "audio/mp3", etc.
+}
+
+/**
+ * Video content.
+ */
+export interface VideoByte {
+  data: Uint8Array | string;
+  mime: string;
+}
+
+/**
+ * Memory content - the smallest coherent unit of memory.
+ *
+ * May contain multiple modalities (e.g., captioned image, video with transcript).
+ * At most one of each modality type.
+ */
+export interface MemoryByte {
+  text?: TextByte;
+  image?: ImageByte;
+  audio?: AudioByte;
+  video?: VideoByte;
+  object?: JSONObject;
+}
+
+/**
+ * Search-ready projection of a MemoryByte.
+ *
+ * Contains canonical text plus embeddings for each modality.
+ */
+export interface IndexableByte {
+  text?: string; // canonical semantic text
+  tvec?: number[]; // text embedding
+  ivec?: number[]; // image embedding
+  avec?: number[]; // audio embedding
+  vvec?: number[]; // video embedding
+  metadata?: JSONObject | null; // structured payload
+}
+
+/**
+ * Encoder that converts MemoryByte to IndexableByte with embeddings.
+ */
+export interface MemoryByteCodec extends AsyncCodec<MemoryByte, IndexableByte> {
+  embed(text: string): Promise<number[]>;
+}
+
+// -------------------
+// Config & snapshots
+// -------------------
+
+export interface MemoryConfig {
+  store: MemoryStore;
+  search?: IndexHandle<IndexMemoryRecord>;
+  // graph?: MemoryGraphIndex;
+  // archive?: MemoryArchiveIndex;
+
+  /** Encoder for converting MemoryByte to IndexableByte with embeddings. */
+  encoder: MemoryByteCodec;
+}
+
+/**
+ * Working memory snapshot (L1).
+ */
+export interface WorkingMemorySnapshot {
+  scope: MemoryScope;
+  records: MemoryRecord[];
+}
+
+/**
+ * Short-term memory snapshot (L2).
+ */
+export interface ShortTermMemorySnapshot {
+  scope: MemoryScope;
+  records: MemoryRecord[];
+}
+
+/**
+ * Memory scope - identifies who/what this memory belongs to.
+ */
+export interface MemoryScope {
+  namespace?: string;
+  entityId?: string;
+  agentId?: string;
+}
+
+/**
+ * Memory kind - episodic (events/experiences) or semantic (facts/knowledge).
+ */
+export type MemoryKind = "episodic" | "semantic";
+
+/**
+ * Input for creating a new memory.
+ */
+export interface NewMemory {
+  id: string;
+  scope: MemoryScope;
+  kind: MemoryKind;
+  collection: string;
+  content: MemoryByte;
+  wmem?: boolean;
+  smem?: { expiresAt: number | null };
+  timestamp?: number;
+  metadata?: JSONObject | null;
+}
+
+/**
+ * Simplified input for agent-scoped memory creation.
+ *
+ * Sugar over NewMemory with:
+ * - id auto-generated if not provided
+ * - scope fields flattened (namespace, entityId) - agentId is implicit
+ * - kind defaults to "semantic"
+ */
+export interface AgentMemoryCreate {
+  id?: string;
+  namespace?: string;
+  entityId?: string;
+  collection: string;
+  content: MemoryByte;
+  wmem?: boolean;
+  smem?: { expiresAt: number | null };
+  timestamp?: number;
+  metadata?: JSONObject | null;
+}
+
+/**
+ * Base memory record fields.
+ */
+interface BaseMemoryRecord {
+  id: string;
+  scope: MemoryScope;
+  kind: MemoryKind;
+  collection: string;
+  content: MemoryByte;
+  wmem: boolean;
+  smem: { expiresAt: number | null };
+  timestamp: number;
+  createdAt: number;
+  updatedAt: number;
+  metadata: JSONObject | null;
+}
+
+/**
+ * Episodic memory - events, experiences, conversations.
+ */
+export interface EpisodicMemoryRecord extends BaseMemoryRecord {
+  kind: "episodic";
+}
+
+/**
+ * Semantic memory - facts, knowledge, learned information.
+ */
+export interface SemanticMemoryRecord extends BaseMemoryRecord {
+  kind: "semantic";
+}
+
+/**
+ * A persisted memory record.
+ */
+export type MemoryRecord = EpisodicMemoryRecord | SemanticMemoryRecord;
+
+/**
+ * Update payload for a memory record.
+ */
+export interface MemoryRecordUpdate {
+  id: string;
+  scope?: MemoryScope;
+  collection?: string;
+  content?: MemoryByte;
+  wmem?: boolean;
+  smem?: { expiresAt: number | null };
+  timestamp?: number;
+  updatedAt?: number;
+  metadata?: JSONObject | null;
+}
+
+/**
+ * Filter for listing memories.
+ */
+export interface MemoryFilter {
+  scope?: Partial<MemoryScope>;
+  collections?: string[];
+  wmem?: boolean;
+  smem?: boolean;
+  after?: number;
+  before?: number;
+  metadata?: JSONObject;
+}
+
+/**
+ * Options for listing memories.
+ */
+export interface MemoryListOptions {
+  filter?: MemoryFilter;
+  limit?: number;
+  offset?: number;
+  order?: "asc" | "desc";
+}
+
+/**
+ * Query for semantic memory search.
+ */
+export interface MemorySearchQuery {
+  query: string;
+  filter?: MemoryFilter;
+  limit?: number;
+}
+
+/**
+ * Params for triggering reindexing of a memory record.
+ */
+export interface MemoryReindexParams {
+  id: string;
+  indexes?: ("search" | "graph" | "archive")[];
+}
+
+// -------------------
+// Index types
+// -------------------
+
+/**
+ * Flat document for search indexes.
+ */
+export interface IndexMemoryRecord extends IndexableByte {
+  id: string;
+  namespace: string | null;
+  entityId: string | null;
+  agentId: string | null;
+  kind: MemoryKind;
+  collection: string;
+  timestamp: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/**
+ * Patch payload for updating an IndexMemoryRecord.
+ * Content changes require full re-index, not a patch.
+ */
+export interface IndexMemoryRecordPatch {
+  id: string;
+  namespace?: string | null;
+  entityId?: string | null;
+  agentId?: string | null;
+  collection?: string;
+  timestamp?: number;
+  updatedAt?: number;
+  metadata?: JSONObject | null;
+}

package/src/storage/__tests__/in-memory.test.ts

@@ -5,7 +5,7 @@ import { InMemoryStorage, InMemoryThreadStore } from "../in-memory";
 import { Agent } from "@/agent";
 import { Thread } from "@/thread";
 import type { NewThread } from "@/storage";
-import type { ThreadEvent } from "@/types/thread";
+import type { ThreadEvent } from "@/thread/types";
 import { createMockModel } from "@/thread/__tests__/fixtures/mock-model";
 
 describe("InMemoryThreadStore", () => {

package/src/storage/base.ts

@@ -2,8 +2,9 @@
  * Core storage contracts.
  */
 
-import type { AgentRegistry, ModelRegistry } from "@/types/kernl";
+import type { AgentRegistry, ModelRegistry } from "@/kernl/types";
 import type { ThreadStore } from "./thread";
+import type { MemoryStore } from "@/memory/store";
 
 /**
  * The main storage interface for Kernl.
@@ -16,6 +17,11 @@ export interface KernlStorage {
    */
   threads: ThreadStore;
 
+  /**
+   * Memory store - manages memory records for agents.
+   */
+  memories: MemoryStore;
+
   // tasks: TaskStore;
   // traces: TraceStore;
 

package/src/storage/in-memory.ts

@@ -23,17 +23,27 @@ import type {
   ThreadFilter,
   SortOrder,
 } from "@/storage";
-import type { ThreadEvent, ThreadState } from "@/types/thread";
-import type { AgentRegistry, ModelRegistry } from "@/types/kernl";
+import type { ThreadEvent, ThreadState } from "@/thread/types";
+import type { AgentRegistry, ModelRegistry } from "@/kernl/types";
+import type {
+  MemoryStore,
+  MemoryRecord,
+  NewMemory,
+  MemoryRecordUpdate,
+  MemoryListOptions,
+  MemoryFilter,
+} from "@/memory";
 
 /**
  * In-memory storage implementation.
  */
 export class InMemoryStorage implements KernlStorage {
   threads: InMemoryThreadStore;
+  memories: InMemoryMemoryStore;
 
   constructor() {
     this.threads = new InMemoryThreadStore();
+    this.memories = new InMemoryMemoryStore();
   }
 
   bind(registries: { agents: AgentRegistry; models: ModelRegistry }): void {
@@ -370,3 +380,161 @@ export class InMemoryThreadStore implements ThreadStore {
     });
   }
 }
+
+/**
+ * In-memory memory store implementation.
+ */
+export class InMemoryMemoryStore implements MemoryStore {
+  private memories = new Map<string, MemoryRecord>();
+
+  async get(id: string): Promise<MemoryRecord | null> {
+    return this.memories.get(id) ?? null;
+  }
+
+  async list(options?: MemoryListOptions): Promise<MemoryRecord[]> {
+    let records = Array.from(this.memories.values());
+
+    // Apply filters
+    if (options?.filter) {
+      records = this.applyFilters(records, options.filter);
+    }
+
+    // Apply sorting
+    records = this.applySorting(records, options?.order);
+
+    // Apply pagination
+    if (options?.offset) records = records.slice(options.offset);
+    if (options?.limit) records = records.slice(0, options.limit);
+
+    return records;
+  }
+
+  async create(memory: NewMemory): Promise<MemoryRecord> {
+    const now = Date.now();
+    const record: MemoryRecord = {
+      id: memory.id,
+      scope: memory.scope,
+      kind: memory.kind,
+      collection: memory.collection,
+      content: memory.content,
+      wmem: memory.wmem ?? false,
+      smem: memory.smem ?? { expiresAt: null },
+      timestamp: memory.timestamp ?? now,
+      createdAt: now,
+      updatedAt: now,
+      metadata: memory.metadata ?? null,
+    };
+
+    this.memories.set(memory.id, record);
+    return record;
+  }
+
+  async update(id: string, patch: MemoryRecordUpdate): Promise<MemoryRecord> {
+    const record = this.memories.get(id);
+    if (!record) throw new Error(`Memory ${id} not found`);
+
+    const updated: MemoryRecord = {
+      ...record,
+      ...(patch.scope && { scope: patch.scope }),
+      ...(patch.collection && { collection: patch.collection }),
+      ...(patch.content && { content: patch.content }),
+      ...(patch.wmem !== undefined && { wmem: patch.wmem }),
+      ...(patch.smem && { smem: patch.smem }),
+      ...(patch.timestamp && { timestamp: patch.timestamp }),
+      ...(patch.metadata !== undefined && { metadata: patch.metadata }),
+      updatedAt: patch.updatedAt ?? Date.now(),
+    };
+
+    this.memories.set(id, updated);
+    return updated;
+  }
+
+  async delete(id: string): Promise<void> {
+    this.memories.delete(id);
+  }
+
+  async mdelete(ids: string[]): Promise<void> {
+    for (const id of ids) {
+      this.memories.delete(id);
+    }
+  }
+
+  /**
+   * Apply filters to memory list.
+   */
+  private applyFilters(
+    records: MemoryRecord[],
+    filter: MemoryFilter,
+  ): MemoryRecord[] {
+    return records.filter((record) => {
+      // Filter by scope
+      if (filter.scope) {
+        if (
+          filter.scope.namespace !== undefined &&
+          record.scope.namespace !== filter.scope.namespace
+        ) {
+          return false;
+        }
+        if (
+          filter.scope.entityId !== undefined &&
+          record.scope.entityId !== filter.scope.entityId
+        ) {
+          return false;
+        }
+        if (
+          filter.scope.agentId !== undefined &&
+          record.scope.agentId !== filter.scope.agentId
+        ) {
+          return false;
+        }
+      }
+
+      // Filter by collections
+      if (filter.collections && !filter.collections.includes(record.collection)) {
+        return false;
+      }
+
+      // Filter by wmem
+      if (filter.wmem !== undefined && record.wmem !== filter.wmem) {
+        return false;
+      }
+
+      // Filter by smem
+      if (filter.smem !== undefined) {
+        const hasSmem = record.smem.expiresAt !== null;
+        if (filter.smem !== hasSmem) return false;
+      }
+
+      // Filter by timestamp range
+      if (filter.after !== undefined && record.timestamp <= filter.after) {
+        return false;
+      }
+      if (filter.before !== undefined && record.timestamp >= filter.before) {
+        return false;
+      }
+
+      // Filter by metadata (simple equality check for now)
+      if (filter.metadata) {
+        const recordMeta = record.metadata ?? {};
+        for (const [key, value] of Object.entries(filter.metadata)) {
+          if (recordMeta[key] !== value) return false;
+        }
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Apply sorting to memory list.
+   */
+  private applySorting(
+    records: MemoryRecord[],
+    order?: "asc" | "desc",
+  ): MemoryRecord[] {
+    return records.sort((a, b) => {
+      const diff = a.timestamp - b.timestamp;
+      return order === "desc" ? -diff : diff;
+    });
+  }
+}

package/src/storage/thread.ts

@@ -4,7 +4,7 @@
 
 import type { Thread } from "@/thread";
 import type { Context } from "@/context";
-import type { ThreadEvent, ThreadState } from "@/types/thread";
+import type { ThreadEvent, ThreadState } from "@/thread/types";
 
 /* ---- Store ---- */
 

package/src/thread/__tests__/integration.test.ts

@@ -9,7 +9,7 @@ import { tool, Toolkit } from "@/tool";
 
 import { Thread } from "../thread";
 
-import type { ThreadEvent, ThreadStreamEvent } from "@/types/thread";
+import type { ThreadEvent, ThreadStreamEvent } from "@/thread/types";
 import type { LanguageModelItem } from "@kernl-sdk/protocol";
 
 /**

package/src/thread/__tests__/mock.ts

@@ -5,7 +5,7 @@ import {
   LanguageModelResponseItem,
   LanguageModelItem,
 } from "@kernl-sdk/protocol";
-import type { ThreadStreamEvent } from "@/types/thread";
+import type { ThreadStreamEvent } from "@/thread/types";
 
 /**
  * A mock language model that echoes the user input back as an assistant message.

package/src/thread/__tests__/thread.test.ts

@@ -11,7 +11,7 @@ import { Context } from "@/context";
 import { tool, FunctionToolkit } from "@/tool";
 import { ModelBehaviorError } from "@/lib/error";
 
-import type { ThreadEvent } from "@/types/thread";
+import type { ThreadEvent } from "@/thread/types";
 import { createMockModel } from "./fixtures/mock-model";
 
 // Helper to create user message input

package/src/thread/thread.ts

@@ -29,8 +29,8 @@ import type {
   ThreadStreamEvent,
   ThreadExecuteResult,
   PerformActionsResult,
-} from "@/types/thread";
-import type { AgentResponseType } from "@/types/agent";
+} from "./types";
+import type { AgentResponseType } from "@/agent/types";
 
 import {
   tevent,
@@ -112,6 +112,7 @@ export class Thread<
     this.agent = options.agent;
     this.context =
       options.context ?? new Context<TContext>(this.namespace, {} as TContext);
+    this.context.agent = options.agent;
     this.parent = options.task ?? null;
     this.model = options.model ?? options.agent.model;
     this.storage = options.storage;
@@ -335,7 +336,7 @@ export class Thread<
       state: this.state,
       tick: this._tick,
       context: this.context,
-      metadata: this.metadata,
+      // no metadata - not owned by checkpoint
     });
   }
 
@@ -441,6 +442,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);
 

package/src/{types/thread.ts → thread/types.ts}

@@ -15,7 +15,7 @@ import { Task } from "@/task";
 import { Context } from "@/context";
 import { Agent } from "@/agent";
 
-import type { AgentResponseType } from "./agent";
+import type { AgentResponseType } from "@/agent/types";
 import type { ThreadStore } from "@/storage";
 
 /**

package/src/thread/utils.ts

@@ -8,14 +8,14 @@ import { ToolCall, LanguageModelItem } from "@kernl-sdk/protocol";
 import { ModelBehaviorError } from "@/lib/error";
 
 /* types */
-import type { AgentResponseType } from "@/types/agent";
+import type { AgentResponseType } from "@/agent/types";
 import type {
   ThreadEvent,
   ThreadEventBase,
   ThreadStreamEvent,
   ActionSet,
   PublicThreadEvent,
-} from "@/types/thread";
+} from "./types";
 
 /**
  * Create a ThreadEvent from a LanguageModelItem with thread metadata.

package/src/tool/index.ts

@@ -8,3 +8,6 @@ export type {
   ToolkitFilter,
   ToolkitFilterContext,
 } from "./types";
+
+// --- system toolkits ---
+export { memory } from "./sys";

package/src/tool/sys/index.ts

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