@princetheprogrammerbtw/husk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { T as Tracer } from './tracer-y41CTrNG.js';
+export { N as NoopTracer, b as Span, a as SpanContext, c as SpanKind, S as SpanOptions } from './tracer-y41CTrNG.js';
+
 /**
  * Husk — core type definitions.
  *
@@ -352,6 +355,169 @@ declare class FileStore implements MemoryStore {
     private fileFor;
 }
 
+/**
+ * Husk — vector memory types and interfaces.
+ *
+ * Long-term memory for agents, separate from the short-term
+ * Message[] memory in src/core/memory.ts. Vector stores are queried
+ * by semantic similarity: you provide a query, get back the top-K
+ * most similar past items.
+ *
+ * Design choice: the agent accesses vector memory through TOOLS
+ * (MemorySearch, Remember) rather than automatic injection. This
+ * means:
+ * - The model decides when to recall (avoids noisy "here's some
+ *   vaguely related past conversation" injections)
+ * - The same memory store can be used by multiple agents
+ * - Vector memory integrates with the existing tool framework, no
+ *   agent-loop changes
+ *
+ * The VectorStore interface is intentionally simple so users can
+ * plug in their own backend (Chroma, Pinecone, sqlite-vec, etc.).
+ * Husk ships one in-memory backend for v0.3.0.
+ */
+
+/**
+ * A single memory item: the text, its embedding, and optional
+ * metadata for filtering or display.
+ */
+interface MemoryItem {
+    /** Unique id (caller-provided, allows updates/deletes). */
+    readonly id: string;
+    /** The text content. What the model sees when this is recalled. */
+    readonly content: string;
+    /** Pre-computed embedding vector. */
+    readonly embedding: readonly number[];
+    /** Optional metadata (timestamp, source, tags, etc.). */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The result of a similarity search: the matched item plus its
+ * similarity score (higher = more similar). Score is implementation-
+ * dependent (cosine similarity for the in-memory backend).
+ */
+interface SearchResult {
+    readonly id: string;
+    readonly content: string;
+    readonly score: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface VectorStore {
+    /** Add or update a memory item. */
+    upsert(item: MemoryItem): Promise<void>;
+    /** Search for the top-K most similar items to the query embedding. */
+    search(queryEmbedding: readonly number[], topK: number): Promise<readonly SearchResult[]>;
+    /** Remove a memory by id. No-op if not present. */
+    remove(id: string): Promise<void>;
+    /** List all memory ids (for debugging/inspection). */
+    list(): Promise<readonly string[]>;
+    /** Remove all memories. */
+    clear(): Promise<void>;
+    /** Total count of memories. */
+    count(): Promise<number>;
+}
+interface EmbeddingProvider {
+    /** Generate an embedding vector for the given text. */
+    embed(text: string): Promise<readonly number[]>;
+    /** The dimensionality of the vectors this provider produces. */
+    readonly dimensions: number;
+}
+interface MemoryToolOptions {
+    /** The vector store to read/write. */
+    readonly store: VectorStore;
+    /** The embedding provider (used inside the tools). */
+    readonly embedder: EmbeddingProvider;
+    /**
+     * Default top-K for searches when the agent doesn't specify.
+     * Default: 5.
+     */
+    readonly defaultTopK?: number;
+}
+/**
+ * Build the MemorySearch tool: agent calls it with a natural-
+ * language query, gets back the top-K most similar past items.
+ */
+declare function defineMemorySearchTool(options: MemoryToolOptions): ToolDefinition<{
+    query: string;
+    topK?: number;
+}>;
+/**
+ * Build the Remember tool: agent calls it to save a fact/observation
+ * to long-term memory for later recall.
+ */
+declare function defineRememberTool(options: MemoryToolOptions): ToolDefinition<{
+    id: string;
+    content: string;
+}>;
+
+/**
+ * Husk — in-memory vector store.
+ *
+ * Naive O(n) linear scan with cosine similarity. Fine for thousands
+ * of memories; slow for millions. The VectorStore interface is
+ * pluggable so users can swap in Chroma, Pinecone, sqlite-vec, or
+ * any ANN index for production scale.
+ *
+ * Why we ship this: zero external dependencies, deterministic
+ * behavior for testing, good enough for the common case of
+ * "remember user preferences across sessions" (a few hundred items).
+ *
+ * For very large stores, see:
+ * - chroma (separate server, ~3-line adapter)
+ * - pinecone (managed, REST API)
+ * - sqlite-vec (in-process, single binary)
+ * - hnswlib-node (in-process, true ANN)
+ */
+
+declare class InMemoryVectorStore implements VectorStore {
+    private readonly items;
+    upsert(item: MemoryItem): Promise<void>;
+    search(queryEmbedding: readonly number[], topK: number): Promise<readonly SearchResult[]>;
+    remove(id: string): Promise<void>;
+    list(): Promise<readonly string[]>;
+    clear(): Promise<void>;
+    count(): Promise<number>;
+}
+/**
+ * Cosine similarity in [-1, 1]. Returns 0 if either vector is zero.
+ * (1.0 = identical direction, 0 = orthogonal, -1 = opposite)
+ */
+declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+
+/**
+ * Husk — simple embedding provider for testing and offline use.
+ *
+ * Produces deterministic pseudo-embeddings from text by hashing
+ * character n-grams into a fixed-dimension vector. NOT a real
+ * embedding model — semantic quality is poor, but it's:
+ *
+ * - Deterministic (same text → same vector)
+ * - Zero-dependency (no API call, no model file)
+ * - Useful for tests, demos, and offline development
+ *
+ * For real semantic search, use a real EmbeddingProvider:
+ * - OpenAIEmbedder (text-embedding-3-small, 1536 dims)
+ * - sentence-transformers via a small Python sidecar
+ * - CohereEmbedder, VoyageEmbedder, etc.
+ *
+ * The "similarity" this produces is bag-of-chars similarity, not
+ * semantic similarity. Two texts with similar character n-grams
+ * will score high even if they mean different things.
+ */
+
+interface HashEmbedderOptions {
+    /** Output vector dimensions. Default: 256. */
+    readonly dimensions?: number;
+    /** N-gram size for the hashing. Default: 3 (trigrams). */
+    readonly ngramSize?: number;
+}
+declare class HashEmbedder implements EmbeddingProvider {
+    readonly dimensions: number;
+    private readonly ngramSize;
+    constructor(options?: HashEmbedderOptions);
+    embed(text: string): Promise<readonly number[]>;
+}
+
 /**
  * Husk — steering prompt builder.
  *
@@ -865,69 +1031,6 @@ declare function defineSuite(suite: {
     cases: readonly EvalCase[];
 }): EvalSuite;
 
-/**
- * Husk — observability types (tracer interface).
- *
- * A minimal, OTel-inspired tracer interface. Husk's events are mapped
- * to spans by the mapper in ./tracer.ts. Users can plug in the real
- * @opentelemetry/api tracer via the adapter (see ./otel-adapter.ts)
- * or any other compatible backend.
- *
- * Design choice: we don't depend on @opentelemetry/api directly. The
- * interface here is a strict subset of OTel's Span interface (just
- * what's needed for agent observability). Keeping the dep out of
- * Husk's core means users who don't need OTel pay nothing for it.
- *
- * For users who want full OTel:
- *   import { trace } from '@opentelemetry/api';
- *   import { toOtelTracer } from '@princetheprogrammerbtw/husk/otel-adapter';
- *   agent.onAny(toOtelTracer(trace.getTracer('husk')).onEvent);
- */
-type SpanKind = 'internal' | 'client' | 'server';
-interface SpanContext {
-    /** Unique trace id (all spans in one agent.run share this). */
-    readonly traceId: string;
-    /** Unique span id. */
-    readonly spanId: string;
-    /** Parent span id, if any. */
-    readonly parentSpanId?: string;
-}
-interface SpanOptions {
-    readonly name: string;
-    readonly kind?: SpanKind;
-    readonly attributes?: Readonly<Record<string, unknown>>;
-    readonly startTimeNs?: bigint;
-}
-interface Span {
-    readonly context: SpanContext;
-    /** Record an event (timestamped annotation) on the span. */
-    addEvent(name: string, attributes?: Record<string, unknown>): void;
-    /** Set or update an attribute on the span. */
-    setAttribute(key: string, value: string | number | boolean | null): void;
-    /** Record an exception. */
-    recordException(err: Error): void;
-    /** Mark the span as failed. */
-    setStatus(status: 'ok' | 'error', message?: string): void;
-    /** End the span. Must be called exactly once. */
-    end(endTimeNs?: bigint): void;
-}
-interface Tracer {
-    /**
-     * Start a new span. If parent is provided, the new span becomes a
-     * child of it. Returns the new span; caller is responsible for
-     * calling .end() on it.
-     */
-    startSpan(options: SpanOptions, parent?: SpanContext): Span;
-}
-/**
- * A tracer that does nothing. Used when no real tracer is configured.
- * Zero overhead — every method is a no-op, so the cost is one virtual
- * call per event.
- */
-declare class NoopTracer implements Tracer {
-    startSpan(_options: SpanOptions, _parent?: SpanContext): Span;
-}
-
 /**
  * Husk — agent event → tracer mapper.
  *
@@ -967,4 +1070,4 @@ declare class EventTracer {
  */
 declare const VERSION = "0.1.0";
 
-export { Agent, type AgentConfig, type AgentEvent, AgentEventEmitter, type AgentEventHandler, type AgentFactory, type AgentResult, AnthropicProvider, type AnthropicProviderOptions, type Assertion, type AssertionResult, Bash, type BashInput, type CaseResult, type ChatChunk, type ChatRequest, type ChatResponse, ConsoleLogger, type ContentBlock, Edit, type EditInput, type EvalCase, type EvalSuite, EventTracer, type Example, FileStore, type FileStoreOptions, Grep, type GrepInput, InMemoryStore, type JSONSchema, type JSONSchemaField, type LogLevel, type Logger, type MemoryStore, type Message, type MessageContent, NoopTracer, OllamaProvider, type OllamaProviderOptions, OpenAIProvider, type OpenAIProviderOptions, type Provider, Read, type ReadInput, type Role, type RunSuiteOptions, type Span, type SpanContext, type SpanKind, type SpanOptions, type SteeringConfig, type StopReason, type SuiteResult, type TextBlock, type TokenUsage, type ToolContext, type ToolDefinition, type ToolResult, type ToolResultBlock, type ToolUseBlock, type Tracer, VERSION, Write, type WriteInput, arrayField, booleanField, buildExampleMessages, buildSystemPrompt, contains, defineSuite, defineTool, equals, fn, integerField, lengthBetween, logEventsTo, matches, notContains, numberField, objectField, objectSchema, runSuite, stringField };
+export { Agent, type AgentConfig, type AgentEvent, AgentEventEmitter, type AgentEventHandler, type AgentFactory, type AgentResult, AnthropicProvider, type AnthropicProviderOptions, type Assertion, type AssertionResult, Bash, type BashInput, type CaseResult, type ChatChunk, type ChatRequest, type ChatResponse, ConsoleLogger, type ContentBlock, Edit, type EditInput, type EmbeddingProvider, type EvalCase, type EvalSuite, EventTracer, type Example, FileStore, type FileStoreOptions, Grep, type GrepInput, HashEmbedder, type HashEmbedderOptions, InMemoryStore, InMemoryVectorStore, type JSONSchema, type JSONSchemaField, type LogLevel, type Logger, type MemoryItem, type MemoryStore, type MemoryToolOptions, type Message, type MessageContent, OllamaProvider, type OllamaProviderOptions, OpenAIProvider, type OpenAIProviderOptions, type Provider, Read, type ReadInput, type Role, type RunSuiteOptions, type SearchResult, type SteeringConfig, type StopReason, type SuiteResult, type TextBlock, type TokenUsage, type ToolContext, type ToolDefinition, type ToolResult, type ToolResultBlock, type ToolUseBlock, Tracer, VERSION, type VectorStore, Write, type WriteInput, arrayField, booleanField, buildExampleMessages, buildSystemPrompt, contains, cosineSimilarity, defineMemorySearchTool, defineRememberTool, defineSuite, defineTool, equals, fn, integerField, lengthBetween, logEventsTo, matches, notContains, numberField, objectField, objectSchema, runSuite, stringField };

package/dist/index.js

@@ -235,6 +235,138 @@ function sanitize(sessionId) {
   return sessionId.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
 
+// src/memory/vector-inmemory.ts
+var InMemoryVectorStore = class {
+  items = /* @__PURE__ */ new Map();
+  async upsert(item) {
+    this.items.set(item.id, item);
+  }
+  async search(queryEmbedding, topK) {
+    if (this.items.size === 0) return [];
+    if (topK <= 0) return [];
+    const scored = [];
+    for (const item of this.items.values()) {
+      const score = cosineSimilarity(queryEmbedding, item.embedding);
+      scored.push({
+        id: item.id,
+        content: item.content,
+        score,
+        ...item.metadata ? { metadata: item.metadata } : {}
+      });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+  async remove(id) {
+    this.items.delete(id);
+  }
+  async list() {
+    return [...this.items.keys()];
+  }
+  async clear() {
+    this.items.clear();
+  }
+  async count() {
+    return this.items.size;
+  }
+};
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+  }
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    const ai = a[i] ?? 0;
+    const bi = b[i] ?? 0;
+    dot += ai * bi;
+    normA += ai * ai;
+    normB += bi * bi;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denom === 0) return 0;
+  return dot / denom;
+}
+
+// src/memory/embedder-hash.ts
+var HashEmbedder = class {
+  dimensions;
+  ngramSize;
+  constructor(options = {}) {
+    this.dimensions = options.dimensions ?? 256;
+    this.ngramSize = options.ngramSize ?? 3;
+  }
+  async embed(text) {
+    const vec = new Array(this.dimensions).fill(0);
+    const normalized = text.toLowerCase();
+    for (let i = 0; i <= normalized.length - this.ngramSize; i++) {
+      const ngram = normalized.slice(i, i + this.ngramSize);
+      const hash = simpleHash(ngram);
+      const idx = hash % this.dimensions;
+      vec[idx] = (vec[idx] ?? 0) + (hash % 2 === 0 ? 1 : -1);
+    }
+    const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+    if (norm === 0) return vec;
+    return vec.map((v) => v / norm);
+  }
+};
+function simpleHash(s) {
+  let hash = 5381;
+  for (let i = 0; i < s.length; i++) {
+    hash = hash * 33 ^ s.charCodeAt(i);
+  }
+  return hash >>> 0;
+}
+
+// src/memory/vector.ts
+function defineMemorySearchTool(options) {
+  const { store, embedder, defaultTopK = 5 } = options;
+  return {
+    name: "MemorySearch",
+    description: "Search long-term memory for past interactions. Use this when the user references something you might have seen before, or when you need context that is not in the current conversation.",
+    inputSchema: makeMemorySearchSchema(),
+    execute: async (input) => {
+      const embedding = await embedder.embed(input.query);
+      const topK = input.topK ?? defaultTopK;
+      const results = await store.search(embedding, topK);
+      if (results.length === 0) {
+        return { output: "No matching memories found." };
+      }
+      return {
+        output: results.map((r) => `[score=${r.score.toFixed(3)}] ${r.content}`).join("\n")
+      };
+    }
+  };
+}
+function defineRememberTool(options) {
+  const { store, embedder } = options;
+  return {
+    name: "Remember",
+    description: "Save a piece of information to long-term memory. The next time you (or another agent) need this, call MemorySearch to recall it. Use this for user preferences, important decisions, or any fact that should survive across sessions.",
+    inputSchema: makeRememberSchema(),
+    execute: async (input) => {
+      const embedding = await embedder.embed(input.content);
+      await store.upsert({ id: input.id, content: input.content, embedding });
+      return { output: `Remembered: ${input.content.slice(0, 80)}` };
+    }
+  };
+}
+function makeMemorySearchSchema() {
+  const properties = {
+    query: { type: "string", description: "Natural-language search query." },
+    topK: { type: "integer", description: "Number of results to return. Default: 5." }
+  };
+  return { type: "object", properties, required: ["query"] };
+}
+function makeRememberSchema() {
+  const properties = {
+    id: { type: "string", description: "Unique identifier for this memory (caller-provided)." },
+    content: { type: "string", description: "The text to remember." }
+  };
+  return { type: "object", properties, required: ["id", "content"] };
+}
+
 // src/core/steering.ts
 function buildSystemPrompt(steering) {
   const parts = [];
@@ -1411,6 +1543,6 @@ var EventTracer = class {
 // src/index.ts
 var VERSION = "0.1.0";
 
-export { Agent, AgentEventEmitter, AnthropicProvider, Bash, ConsoleLogger, Edit, EventTracer, FileStore, Grep, InMemoryStore, NoopTracer, OllamaProvider, OpenAIProvider, Read, VERSION, Write, arrayField, booleanField, buildExampleMessages, buildSystemPrompt, contains, defineSuite, defineTool, equals, fn, integerField, lengthBetween, logEventsTo, matches, notContains, numberField, objectField, objectSchema, runSuite, stringField };
+export { Agent, AgentEventEmitter, AnthropicProvider, Bash, ConsoleLogger, Edit, EventTracer, FileStore, Grep, HashEmbedder, InMemoryStore, InMemoryVectorStore, NoopTracer, OllamaProvider, OpenAIProvider, Read, VERSION, Write, arrayField, booleanField, buildExampleMessages, buildSystemPrompt, contains, cosineSimilarity, defineMemorySearchTool, defineRememberTool, defineSuite, defineTool, equals, fn, integerField, lengthBetween, logEventsTo, matches, notContains, numberField, objectField, objectSchema, runSuite, stringField };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map