hoomanjs 1.18.0 → 1.18.1

package/src/core/memory/ltm/embed.ts

@@ -1,67 +0,0 @@
-import { pipeline } from "@huggingface/transformers";
-import type { FeatureExtractionPipeline } from "@huggingface/transformers";
-import type { EmbeddingFunction } from "chromadb";
-
-const DEFAULT_MODEL =
-  process.env.HF_EMBEDDING_MODEL ?? "Xenova/bge-small-en-v1.5";
-
-/**
- * Chroma {@link EmbeddingFunction} backed by `@huggingface/transformers`
- * `feature-extraction` (mean-pooled, L2-normalized sentence embeddings).
- *
- * The pipeline is loaded lazily on first {@link HFEmbedding.generate} call so
- * constructors stay synchronous and startup stays fast.
- */
-export class HFEmbedding implements EmbeddingFunction {
-  private readonly modelId: string;
-  private pipePromise: Promise<FeatureExtractionPipeline> | null = null;
-
-  constructor(modelId: string = DEFAULT_MODEL) {
-    this.modelId = modelId;
-  }
-
-  get name(): string {
-    return `hf-transformers:${this.modelId}`;
-  }
-
-  private async getPipeline(): Promise<FeatureExtractionPipeline> {
-    if (!this.pipePromise) {
-      this.pipePromise = pipeline(
-        "feature-extraction",
-        this.modelId,
-      ) as Promise<FeatureExtractionPipeline>;
-    }
-    return this.pipePromise;
-  }
-
-  async generate(texts: string[]): Promise<number[][]> {
-    if (texts.length === 0) {
-      return [];
-    }
-    const pipe = await this.getPipeline();
-    const tensor = await pipe(texts, {
-      pooling: "mean",
-      normalize: true,
-    });
-    const raw = tensor.tolist() as unknown;
-
-    if (texts.length === 1) {
-      if (Array.isArray(raw) && raw.every((x) => typeof x === "number")) {
-        return [raw as number[]];
-      }
-    }
-
-    if (
-      Array.isArray(raw) &&
-      raw.length > 0 &&
-      Array.isArray(raw[0]) &&
-      (raw[0] as unknown[]).every((x) => typeof x === "number")
-    ) {
-      return raw as number[][];
-    }
-
-    throw new Error(
-      "Unexpected embedding tensor shape from feature-extraction pipeline",
-    );
-  }
-}

package/src/core/memory/ltm/index.ts

@@ -1,18 +0,0 @@
-export {
-  LongTermMemoryStore,
-  create as createLongTermMemoryStore,
-} from "./store.ts";
-
-export { create as createLongTermMemoryTools } from "./tools.ts";
-
-export type {
-  ArchiveMemoryInput,
-  LongTermMemoryOptions,
-  LongTermMemoryScope,
-  MemorySource,
-  SearchMemoryInput,
-  SearchMemoryResult,
-  StoreMemoryInput,
-  StoreMemoryResult,
-  UpdateMemoryInput,
-} from "./types.ts";

package/src/core/memory/ltm/store.ts

@@ -1,376 +0,0 @@
-import { ChromaClient } from "chromadb";
-import type { QueryRowResult } from "chromadb";
-import { HFEmbedding } from "./embed.ts";
-import type {
-  ArchiveMemoryInput,
-  LongTermMemoryOptions,
-  LongTermMemoryScope,
-  Memory,
-  SearchMemoryInput,
-  SearchMemoryResult,
-  StoreMemoryInput,
-  StoreMemoryResult,
-  UpdateMemoryInput,
-} from "./types.ts";
-import type { Config } from "../../config.ts";
-import {
-  DEFAULT_DEDUPE_THRESHOLD,
-  DEFAULT_HALF_LIFE_MS,
-  DEFAULT_REINFORCEMENT_STEP,
-  type ChromaMemoryMetadata,
-  buildWhere,
-  chromaClientArgsFromUrl,
-  clampSearchLimit,
-  clampUnitInterval,
-  getEffectiveStrength,
-  similarity,
-  toChromaMetadata,
-  toMemory,
-} from "./utils.ts";
-
-type Collection = Awaited<ReturnType<ChromaClient["getOrCreateCollection"]>>;
-
-export class LongTermMemoryStore {
-  private readonly client: ChromaClient;
-  private collectionPromise: Promise<Collection> | null = null;
-
-  public constructor(
-    private readonly config: Config,
-    private readonly options: LongTermMemoryOptions = {},
-  ) {
-    this.client = new ChromaClient({
-      ...chromaClientArgsFromUrl(config.ltm.chroma.url),
-    });
-  }
-
-  private async collection(): Promise<Collection> {
-    if (!this.collectionPromise) {
-      this.collectionPromise = this.client.getOrCreateCollection({
-        name: this.config.ltm.chroma.collection.memory,
-        embeddingFunction: new HFEmbedding(),
-      });
-    }
-    return this.collectionPromise;
-  }
-
-  public async count(scope?: LongTermMemoryScope): Promise<number> {
-    const collection = await this.collection();
-    if (!scope) {
-      return collection.count();
-    }
-    const result = await collection.get({
-      where: buildWhere(scope, { includeArchived: true }),
-      include: [],
-    });
-    return result.ids.length;
-  }
-
-  public async get(id: string): Promise<Memory | null> {
-    const collection = await this.collection();
-    const result = await collection.get<ChromaMemoryMetadata>({
-      ids: [id],
-      include: ["documents", "metadatas"],
-    });
-    const content = result.documents[0];
-    const metadata = result.metadatas[0];
-    if (!content) {
-      return null;
-    }
-    return toMemory(id, content, metadata);
-  }
-
-  public async search(input: SearchMemoryInput): Promise<SearchMemoryResult[]> {
-    const collection = await this.collection();
-    const result = await collection.query<ChromaMemoryMetadata>({
-      queryTexts: [input.query],
-      nResults: clampSearchLimit(input.limit),
-      where: buildWhere(input.scope, {
-        includeArchived: input.includeArchived,
-        types: input.types,
-      }),
-      include: ["documents", "metadatas", "distances"],
-    });
-
-    const rows = (result.rows()[0] ??
-      []) as QueryRowResult<ChromaMemoryMetadata>[];
-    const memories = rows
-      .filter(
-        (
-          row: QueryRowResult<ChromaMemoryMetadata>,
-        ): row is QueryRowResult<ChromaMemoryMetadata> & {
-          document: string;
-          metadata: ChromaMemoryMetadata;
-        } => typeof row.document === "string" && !!row.metadata,
-      )
-      .map(
-        (
-          row: QueryRowResult<ChromaMemoryMetadata> & {
-            document: string;
-            metadata: ChromaMemoryMetadata;
-          },
-        ) => {
-          const memory = toMemory(row.id, row.document, row.metadata);
-          return {
-            ...memory,
-            distance: row.distance,
-            effectiveStrength: getEffectiveStrength(
-              memory.metadata,
-              this.options.halfLifeMs ?? DEFAULT_HALF_LIFE_MS,
-            ),
-          } satisfies SearchMemoryResult;
-        },
-      );
-
-    if (input.reinforce !== false && memories.length > 0) {
-      await Promise.all(
-        memories.map((memory: SearchMemoryResult) => this.reinforce(memory)),
-      );
-    }
-
-    return memories;
-  }
-
-  public async store(
-    input: StoreMemoryInput,
-    scope: LongTermMemoryScope,
-  ): Promise<StoreMemoryResult> {
-    const collection = await this.collection();
-    const content = input.content.trim();
-    if (!content) {
-      throw new Error("Long-term memory content cannot be empty");
-    }
-
-    if (input.dedupe !== false) {
-      const duplicate = await this.findDuplicate(content, scope);
-      if (duplicate) {
-        const merged = await this.mergeDuplicate(duplicate, input);
-        return {
-          id: merged.id,
-          merged: true,
-          memory: merged,
-        };
-      }
-    }
-
-    const now = Date.now();
-    const memory: Memory = {
-      id: crypto.randomUUID(),
-      userId: scope.userId,
-      type: input.type,
-      status: "active",
-      content,
-      metadata: {
-        createdAt: now,
-        updatedAt: now,
-        importance: clampUnitInterval(input.importance ?? 0.7, 0.7),
-        strength: 0.5,
-        accessCount: 0,
-        version: 1,
-        source: input.source ?? "assistant",
-        confidence:
-          input.confidence == null
-            ? undefined
-            : clampUnitInterval(input.confidence, 1),
-        tags: input.tags,
-        entities: input.entities,
-        relatedTo: input.relatedTo,
-      },
-    };
-
-    await collection.add({
-      ids: [memory.id],
-      documents: [memory.content],
-      metadatas: [toChromaMetadata(memory)],
-    });
-
-    return {
-      id: memory.id,
-      merged: false,
-      memory,
-    };
-  }
-
-  public async update(input: UpdateMemoryInput): Promise<Memory> {
-    const existing = await this.get(input.id);
-    if (!existing) {
-      throw new Error(`Memory not found: ${input.id}`);
-    }
-    const content = input.content.trim();
-    if (!content) {
-      throw new Error("Long-term memory content cannot be empty");
-    }
-
-    const next: Memory = {
-      ...existing,
-      type: input.type ?? existing.type,
-      status: input.status ?? existing.status,
-      content,
-      metadata: {
-        ...existing.metadata,
-        updatedAt: Date.now(),
-        version: existing.metadata.version + 1,
-        importance:
-          input.importance == null
-            ? existing.metadata.importance
-            : clampUnitInterval(input.importance, existing.metadata.importance),
-        confidence:
-          input.confidence == null
-            ? existing.metadata.confidence
-            : clampUnitInterval(
-                input.confidence,
-                existing.metadata.confidence ?? 1,
-              ),
-        tags: input.tags ?? existing.metadata.tags,
-        entities: input.entities ?? existing.metadata.entities,
-        relatedTo: input.relatedTo ?? existing.metadata.relatedTo,
-        supersededBy: input.supersededBy ?? existing.metadata.supersededBy,
-      },
-    };
-
-    const collection = await this.collection();
-    await collection.update({
-      ids: [next.id],
-      documents: [next.content],
-      metadatas: [toChromaMetadata(next)],
-    });
-
-    return next;
-  }
-
-  public async archive(input: ArchiveMemoryInput): Promise<Memory> {
-    const existing = await this.get(input.id);
-    if (!existing) {
-      throw new Error(`Memory not found: ${input.id}`);
-    }
-
-    const archived: Memory = {
-      ...existing,
-      status: input.status ?? "archived",
-      metadata: {
-        ...existing.metadata,
-        updatedAt: Date.now(),
-        version: existing.metadata.version + 1,
-        supersededBy: input.supersededBy ?? existing.metadata.supersededBy,
-      },
-    };
-
-    const collection = await this.collection();
-    await collection.update({
-      ids: [archived.id],
-      documents: [archived.content],
-      metadatas: [toChromaMetadata(archived)],
-    });
-
-    return archived;
-  }
-
-  private async reinforce(memory: Memory): Promise<void> {
-    const updated: Memory = {
-      ...memory,
-      metadata: {
-        ...memory.metadata,
-        strength:
-          memory.metadata.strength +
-          (this.options.reinforcementStep ?? DEFAULT_REINFORCEMENT_STEP),
-        lastAccessedAt: Date.now(),
-        accessCount: memory.metadata.accessCount + 1,
-      },
-    };
-
-    const collection = await this.collection();
-    await collection.update({
-      ids: [updated.id],
-      documents: [updated.content],
-      metadatas: [toChromaMetadata(updated)],
-    });
-  }
-
-  private async findDuplicate(
-    content: string,
-    scope: LongTermMemoryScope,
-  ): Promise<Memory | null> {
-    const collection = await this.collection();
-    const result = await collection.query<ChromaMemoryMetadata>({
-      queryTexts: [content],
-      nResults: 3,
-      where: buildWhere(scope, { status: "active" }),
-      include: ["documents", "metadatas"],
-    });
-
-    const rows = result.rows()[0] ?? [];
-    for (const row of rows) {
-      if (!row.document || !row.metadata) {
-        continue;
-      }
-      if (
-        similarity(row.document, content) >=
-        (this.options.dedupeThreshold ?? DEFAULT_DEDUPE_THRESHOLD)
-      ) {
-        return toMemory(row.id, row.document, row.metadata);
-      }
-    }
-    return null;
-  }
-
-  private async mergeDuplicate(
-    existing: Memory,
-    incoming: StoreMemoryInput,
-  ): Promise<Memory> {
-    const mergedTags = new Set([
-      ...(existing.metadata.tags ?? []),
-      ...(incoming.tags ?? []),
-    ]);
-    const mergedEntities = new Set([
-      ...(existing.metadata.entities ?? []),
-      ...(incoming.entities ?? []),
-    ]);
-    const mergedRelated = new Set([
-      ...(existing.metadata.relatedTo ?? []),
-      ...(incoming.relatedTo ?? []),
-    ]);
-
-    const updated: Memory = {
-      ...existing,
-      metadata: {
-        ...existing.metadata,
-        updatedAt: Date.now(),
-        lastAccessedAt: Date.now(),
-        accessCount: existing.metadata.accessCount + 1,
-        version: existing.metadata.version + 1,
-        strength:
-          existing.metadata.strength +
-          (this.options.reinforcementStep ?? DEFAULT_REINFORCEMENT_STEP),
-        importance: Math.max(
-          existing.metadata.importance,
-          clampUnitInterval(incoming.importance ?? 0.7, 0.7),
-        ),
-        confidence:
-          incoming.confidence == null
-            ? existing.metadata.confidence
-            : Math.max(
-                existing.metadata.confidence ?? 0,
-                clampUnitInterval(incoming.confidence, 1),
-              ),
-        tags: mergedTags.size > 0 ? [...mergedTags] : undefined,
-        entities: mergedEntities.size > 0 ? [...mergedEntities] : undefined,
-        relatedTo: mergedRelated.size > 0 ? [...mergedRelated] : undefined,
-      },
-    };
-
-    const collection = await this.collection();
-    await collection.update({
-      ids: [updated.id],
-      documents: [updated.content],
-      metadatas: [toChromaMetadata(updated)],
-    });
-
-    return updated;
-  }
-}
-
-export function create(
-  config: Config,
-  options?: LongTermMemoryOptions,
-): LongTermMemoryStore {
-  return new LongTermMemoryStore(config, options);
-}

package/src/core/memory/ltm/tools.ts

@@ -1,146 +0,0 @@
-import { tool } from "@strands-agents/sdk";
-import type { JSONValue, ToolContext } from "@strands-agents/sdk";
-import { z } from "zod";
-import type { LongTermMemoryStore } from "./store.ts";
-import type { LongTermMemoryScope, MemoryType } from "./types.ts";
-
-const StoreTypes: [MemoryType, ...MemoryType[]] = [
-  "fact",
-  "preference",
-  "task",
-];
-const SearchTypes: [MemoryType, ...MemoryType[]] = [
-  "fact",
-  "preference",
-  "task",
-  "episodic",
-  "semantic",
-];
-
-function toJsonValue(value: unknown): JSONValue {
-  return JSON.parse(JSON.stringify(value)) as JSONValue;
-}
-
-function resolveScope(context?: ToolContext): LongTermMemoryScope {
-  const userId = context?.agent.appState.get("userId");
-  if (typeof userId !== "string" || userId.trim().length === 0) {
-    throw new Error(
-      "Long-term memory tools require `userId` in agent appState.",
-    );
-  }
-
-  return { userId };
-}
-
-export function create(ltm: LongTermMemoryStore) {
-  return [
-    tool({
-      name: "store_memory",
-      description:
-        "Store important long-term memory. Only use for reusable facts, preferences, or tasks.",
-      inputSchema: z.object({
-        content: z.string().min(1).describe("Compressed memory content"),
-        type: z.enum(StoreTypes),
-        importance: z.number().min(0).max(1).optional(),
-        tags: z.array(z.string()).optional(),
-        entities: z.array(z.string()).optional(),
-      }),
-      callback: async (input, context?: ToolContext) => {
-        const scope = resolveScope(context);
-        const result = await ltm.store(
-          {
-            content: input.content,
-            type: input.type,
-            importance: input.importance,
-            tags: input.tags,
-            entities: input.entities,
-            dedupe: true,
-          },
-          scope,
-        );
-
-        return toJsonValue({
-          id: result.id,
-          merged: result.merged,
-          memory: result.memory,
-        });
-      },
-    }),
-    tool({
-      name: "search_memory",
-      description:
-        "Search relevant past memory for context. Use only if additional context is needed.",
-      inputSchema: z.object({
-        query: z.string().min(1).describe("What to search for"),
-        types: z.array(z.enum(SearchTypes)).optional(),
-        k: z
-          .number()
-          .int()
-          .min(1)
-          .max(20)
-          .optional()
-          .describe("Number of results (default 5, max 20)"),
-      }),
-      callback: async (input, context?: ToolContext) => {
-        const scope = resolveScope(context);
-        const memories = await ltm.search({
-          query: input.query,
-          scope,
-          types: input.types,
-          limit: input.k,
-          reinforce: true,
-        });
-
-        return toJsonValue({
-          count: memories.length,
-          memories,
-        });
-      },
-    }),
-    tool({
-      name: "update_memory",
-      description:
-        "Update or correct an existing memory. Prefer this over deleting.",
-      inputSchema: z.object({
-        id: z.string().min(1),
-        content: z.string().min(1),
-        tags: z.array(z.string()).optional(),
-        entities: z.array(z.string()).optional(),
-      }),
-      callback: async (input) => {
-        const memory = await ltm.update({
-          id: input.id,
-          content: input.content,
-          tags: input.tags,
-          entities: input.entities,
-        });
-
-        return toJsonValue({
-          id: memory.id,
-          memory,
-        });
-      },
-    }),
-    tool({
-      name: "archive_memory",
-      description: "Mark memory as no longer relevant without deleting it.",
-      inputSchema: z.object({
-        id: z.string().min(1),
-        reason: z.string().optional(),
-      }),
-      callback: async (input) => {
-        const memory = await ltm.archive({
-          id: input.id,
-          status: "archived",
-        });
-
-        return toJsonValue({
-          id: memory.id,
-          status: memory.status,
-          reason: input.reason ?? null,
-          memory,
-        });
-      },
-    }),
-  ];
-}

package/src/core/memory/ltm/types.ts

@@ -1,111 +0,0 @@
-export type MemoryStatus = "active" | "archived" | "superseded" | "deleted";
-
-export type MemoryType =
-  | "fact"
-  | "preference"
-  | "task"
-  | "episodic"
-  | "semantic";
-
-export interface Memory {
-  id: string;
-
-  // multi-tenant partitioning
-  userId: string;
-
-  type: MemoryType;
-  status: MemoryStatus;
-
-  content: string; // human-readable
-  embedding?: number[]; // optional (store-level)
-
-  metadata: {
-    // timestamps
-    createdAt: number;
-    updatedAt?: number;
-    lastAccessedAt?: number;
-
-    // scoring
-    importance: number; // write-time signal (0–1)
-    strength: number; // dynamic reinforcement (0–∞)
-    confidence?: number; // extraction confidence
-
-    // lifecycle
-    accessCount: number;
-    version: number;
-
-    // provenance
-    source: "user" | "assistant" | "system" | "inferred";
-
-    // structure
-    tags?: string[];
-    entities?: string[];
-
-    // relationships
-    supersededBy?: string; // memory id
-    relatedTo?: string[]; // graph-lite
-  };
-}
-
-export type MemorySource = Memory["metadata"]["source"];
-
-export interface LongTermMemoryScope {
-  userId: string;
-}
-
-export interface LongTermMemoryOptions {
-  halfLifeMs?: number;
-  reinforcementStep?: number;
-  dedupeThreshold?: number;
-}
-
-export interface StoreMemoryInput {
-  content: string;
-  type: MemoryType;
-  importance?: number;
-  confidence?: number;
-  tags?: string[];
-  entities?: string[];
-  relatedTo?: string[];
-  source?: MemorySource;
-  dedupe?: boolean;
-}
-
-export interface SearchMemoryInput {
-  query: string;
-  scope: LongTermMemoryScope;
-  types?: MemoryType[];
-  limit?: number;
-  includeArchived?: boolean;
-  reinforce?: boolean;
-}
-
-export interface SearchMemoryResult extends Memory {
-  distance?: number | null;
-  effectiveStrength: number;
-}
-
-export interface UpdateMemoryInput {
-  id: string;
-  content: string;
-  type?: MemoryType;
-  status?: MemoryStatus;
-  importance?: number;
-  confidence?: number;
-  tags?: string[];
-  entities?: string[];
-  relatedTo?: string[];
-  supersededBy?: string;
-}
-
-export interface ArchiveMemoryInput {
-  id: string;
-  status?: Extract<MemoryStatus, "archived" | "superseded" | "deleted">;
-  supersededBy?: string;
-}
-
-export interface StoreMemoryResult {
-  id: string;
-  merged: boolean;
-  memory: Memory;
-}