@memstack/core 0.2.0 → 0.4.0

package/src/client.ts

@@ -1,236 +0,0 @@
-import type { Memory, ProcessResult, MemStackSnapshot, HealthStatus } from "./types.js";
-import type { MemStackConfig, ProcessInput, MemoryStoreInput, StorageProvider } from "./interfaces.js";
-import { MemoryStore } from "./memory/MemoryStore.js";
-import { InMemoryStorage } from "./adapters/storage/memory.js";
-import { configError, validationError } from "./errors.js";
-
-export class MemStack {
-  readonly memory: MemoryStore;
-
-  private config: MemStackConfig;
-  private storage: StorageProvider;
-  private processCount = 0;
-
-  constructor(config: MemStackConfig) {
-    if (!config.llm) {
-      throw configError("LLM provider is required");
-    }
-
-    this.config = config;
-    this.storage = config.storage ?? new InMemoryStorage();
-
-    this.memory = new MemoryStore({
-      storage: this.storage,
-      embedding: config.embedding,
-      llm: config.llm,
-      embedOnStore: config.defaults?.embedOnStore ?? true,
-      summarizationPrompt: config.defaults?.summarizationPrompt,
-    });
-  }
-
-  async process(input: ProcessInput): Promise<ProcessResult> {
-    // Auto-enrichment: importance + tags via LLM when not provided
-    let importance = input.importance;
-    let tags = input.tags;
-
-    const needImportance = importance === undefined && this.config.defaults?.autoImportance;
-    const needTags = (!tags || tags.length === 0) && this.config.defaults?.autoTags;
-
-    if (needImportance || needTags) {
-      try {
-        if (needImportance && needTags) {
-          // Batch both into one LLM call
-          const result = await this.config.llm.complete({
-            system:
-              "Analyze the memory and respond with a JSON object: {\"importance\": <0.0-1.0>, \"tags\": [<array of 1-5 lowercase single-word tags>]}. Return ONLY the JSON, nothing else.",
-            user: input.content,
-            maxTokens: 100,
-            temperature: 0,
-          });
-          const parsed = this._parseEnrichmentJson(result.text);
-          if (parsed.importance !== undefined) importance = parsed.importance;
-          if (parsed.tags) tags = parsed.tags;
-        } else if (needImportance) {
-          const result = await this.config.llm.complete({
-            system:
-              "Rate the importance of the following memory for an AI agent on a scale of 0.0 to 1.0, where 0.0 is trivial and 1.0 is critical. Return ONLY a single float number, nothing else.",
-            user: input.content,
-            maxTokens: 10,
-            temperature: 0,
-          });
-          const parsed = parseFloat(result.text.trim());
-          importance = Number.isFinite(parsed) ? Math.max(0, Math.min(1, parsed)) : 0.5;
-        } else if (needTags) {
-          const result = await this.config.llm.complete({
-            system:
-              "Extract 1-5 concise, lowercase, single-word tags from the following memory. Return ONLY a JSON array of strings, nothing else. Example: [\"combat\", \"goblin\", \"forest\"]",
-            user: input.content,
-            maxTokens: 80,
-            temperature: 0,
-          });
-          tags = this._parseTagsJson(result.text);
-        }
-      } catch (err) {
-        this.config.hooks?.onError?.(
-          err instanceof Error ? err : new Error(String(err)),
-          "auto-enrich"
-        );
-        if (importance === undefined) importance = 0.5;
-        if (!tags) tags = [];
-      }
-    }
-
-    const memoryInput: MemoryStoreInput = {
-      actorId: input.actorId,
-      content: input.content,
-      memoryType: input.memoryType ?? "interaction",
-      importance: importance ?? 0.5,
-      emotionalValence: input.emotionalValence ?? 0,
-      tags: tags ?? [],
-      metadata: input.metadata ?? {},
-      expiresAt: input.expiresAt,
-      onConflict: input.onConflict,
-    };
-
-    const memory = await this.memory.store(memoryInput);
-    this.config.hooks?.onMemoryStored?.(memory);
-    this.processCount++;
-
-    // Auto-summarize if threshold is hit
-    let summaryCreated: Memory | undefined;
-    const threshold = this.config.defaults?.summarizationThreshold ?? 100;
-    if (threshold > 0) {
-      const count = await this.memory.count({ actorId: input.actorId, memoryType: "interaction" });
-      if (count % threshold === 0 && count > 0) {
-        try {
-          const result = await this.memory.summarize(
-            {
-              actorId: input.actorId,
-              memoryTypes: ["interaction"],
-              skipMostRecent: 5,
-              targetCount: Math.min(15, count),
-            },
-            this.config.hooks?.onError
-              ? (err) => this.config.hooks!.onError!(err, "summarize")
-              : undefined
-          );
-          summaryCreated = result.summary;
-          this.config.hooks?.onSummaryCreated?.(result.summary, result.deletedCount);
-        } catch (err) {
-          this.config.hooks?.onError?.(
-            err instanceof Error ? err : new Error(String(err)),
-            "summarize"
-          );
-        }
-      }
-    }
-
-    // Auto-prune if configured (throttled)
-    const pruneStrategy = this.config.defaults?.pruneStrategy;
-    const pruneInterval = this.config.defaults?.pruneInterval ?? 100;
-    if (pruneStrategy && this.processCount % pruneInterval === 0) {
-      try {
-        const pruneResult = await this.memory.prune(pruneStrategy);
-        if (pruneResult.count > 0) {
-          this.config.hooks?.onMemoryPruned?.(pruneResult.pruned);
-        }
-      } catch (err) {
-        this.config.hooks?.onError?.(
-          err instanceof Error ? err : new Error(String(err)),
-          "prune"
-        );
-      }
-    }
-
-    return { memory, summaryCreated };
-  }
-
-  async export(): Promise<MemStackSnapshot> {
-    const memories = await this.memory.export();
-    return {
-      version: 1,
-      memories,
-      exportedAt: new Date().toISOString(),
-    };
-  }
-
-  async import(snapshot: MemStackSnapshot): Promise<void> {
-    if (snapshot.version !== 1) {
-      throw validationError(`Unsupported snapshot version: ${snapshot.version}`);
-    }
-    await this.memory.storeBatch(snapshot.memories);
-  }
-
-  async health(): Promise<HealthStatus> {
-    const status: HealthStatus = { storage: false, llm: false, embedding: false };
-
-    try {
-      await this.memory.count();
-      status.storage = true;
-    } catch { /* storage check failed */ }
-
-    try {
-      await this.config.llm.complete({ system: "ok", user: "health", maxTokens: 1 });
-      status.llm = true;
-    } catch { /* llm check failed */ }
-
-    if (this.config.embedding) {
-      try {
-        await this.config.embedding.embed(["health check"]);
-        status.embedding = true;
-      } catch { /* embedding check failed */ }
-    }
-
-    return status;
-  }
-
-  async close(): Promise<void> {
-    await this.storage.close();
-  }
-
-  private _parseEnrichmentJson(
-    text: string
-  ): { importance?: number; tags?: string[] } {
-    try {
-      const json = JSON.parse(this._extractJson(text)) as Record<string, unknown>;
-      const result: { importance?: number; tags?: string[] } = {};
-      if (typeof json.importance === "number" && Number.isFinite(json.importance)) {
-        result.importance = Math.max(0, Math.min(1, json.importance));
-      }
-      if (
-        Array.isArray(json.tags) &&
-        json.tags.every((t: unknown) => typeof t === "string")
-      ) {
-        result.tags = (json.tags as string[]).map((t) => t.toLowerCase().trim()).slice(0, 5);
-      }
-      return result;
-    } catch {
-      return {};
-    }
-  }
-
-  private _parseTagsJson(text: string): string[] {
-    try {
-      const parsed = JSON.parse(this._extractJson(text)) as unknown;
-      if (Array.isArray(parsed) && parsed.every((t: unknown) => typeof t === "string")) {
-        return (parsed as string[]).map((t) => t.toLowerCase().trim()).slice(0, 5);
-      }
-    } catch {
-      // Fallback: try comma-separated
-    }
-    return text
-      .split(",")
-      .map((t) => t.replace(/[\[\]"]/g, "").trim().toLowerCase())
-      .filter((t) => t.length > 0)
-      .slice(0, 5);
-  }
-
-  /** Strip markdown code fences and extract the JSON payload from LLM output. */
-  private _extractJson(text: string): string {
-    let cleaned = text.trim();
-    // Remove ```json ... ``` or ``` ... ``` fences
-    const fenceMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (fenceMatch) cleaned = fenceMatch[1].trim();
-    return cleaned;
-  }
-}

package/src/errors.ts

@@ -1,47 +0,0 @@
-export type MemStackErrorCode =
-  | "STORAGE_ERROR"
-  | "EMBEDDING_ERROR"
-  | "LLM_ERROR"
-  | "VALIDATION_ERROR"
-  | "NOT_FOUND"
-  | "CONFIG_ERROR";
-
-export class MemStackError extends Error {
-  code: MemStackErrorCode;
-  retryable: boolean;
-  details?: Record<string, unknown>;
-
-  constructor(
-    code: MemStackErrorCode,
-    message: string,
-    options: { retryable?: boolean; details?: Record<string, unknown> } = {}
-  ) {
-    super(message);
-    this.name = "MemStackError";
-    this.code = code;
-    this.retryable = options.retryable ?? false;
-    this.details = options.details;
-  }
-}
-
-export function notFound(entity: string, id: string): MemStackError {
-  return new MemStackError("NOT_FOUND", `${entity} not found: ${id}`, {
-    retryable: false,
-    details: { entity, id },
-  });
-}
-
-export function validationError(message: string, details?: Record<string, unknown>): MemStackError {
-  return new MemStackError("VALIDATION_ERROR", message, { details });
-}
-
-export function storageError(message: string, cause?: unknown): MemStackError {
-  return new MemStackError("STORAGE_ERROR", message, {
-    retryable: true,
-    details: { cause: cause instanceof Error ? cause.message : String(cause) },
-  });
-}
-
-export function configError(message: string): MemStackError {
-  return new MemStackError("CONFIG_ERROR", message, { retryable: false });
-}

package/src/index.ts

@@ -1,52 +0,0 @@
-// Main client
-export { MemStack } from "./client.js";
-
-// Types
-export type {
-  Memory,
-  MemoryType,
-  CompiledContext,
-  ProcessResult,
-  MemStackSnapshot,
-  HealthStatus,
-} from "./types.js";
-
-// Interfaces
-export type {
-  MemoryStoreInput,
-  MemoryRetrieveQuery,
-  MemoryCountFilter,
-  ContextOptions,
-  SummarizeOptions,
-  PruneStrategy,
-  LLMProvider,
-  EmbeddingProvider,
-  StorageProvider,
-  MemStackConfig,
-  ProcessInput,
-} from "./interfaces.js";
-
-// Errors
-export { MemStackError, notFound, validationError, storageError, configError } from "./errors.js";
-export type { MemStackErrorCode } from "./errors.js";
-
-// Adapters
-export { InMemoryStorage } from "./adapters/storage/memory.js";
-export { DiskStorage } from "./adapters/storage/disk.js";
-export type { DiskStorageConfig } from "./adapters/storage/disk.js";
-export { RedisStorage } from "./adapters/storage/redis.js";
-export type { RedisStorageConfig } from "./adapters/storage/redis.js";
-export { PostgresStorage } from "./adapters/storage/postgres.js";
-export type { PostgresStorageConfig } from "./adapters/storage/postgres.js";
-export { OpenAILLMAdapter } from "./adapters/llm/openai.js";
-export type { OpenAILLMConfig } from "./adapters/llm/openai.js";
-export { AnthropicLLMAdapter } from "./adapters/llm/anthropic.js";
-export type { AnthropicLLMConfig } from "./adapters/llm/anthropic.js";
-export { OpenAIEmbeddingAdapter } from "./adapters/embedding/openai.js";
-export type { OpenAIEmbeddingConfig } from "./adapters/embedding/openai.js";
-export { CohereEmbeddingAdapter } from "./adapters/embedding/cohere.js";
-export type { CohereEmbeddingConfig } from "./adapters/embedding/cohere.js";
-export { OllamaLLMAdapter } from "./adapters/llm/ollama.js";
-export type { OllamaLLMConfig } from "./adapters/llm/ollama.js";
-export { GroqLLMAdapter } from "./adapters/llm/groq.js";
-export type { GroqLLMConfig } from "./adapters/llm/groq.js";

package/src/interfaces.ts

@@ -1,154 +0,0 @@
-import type { Memory, ProcessResult, MemoryType } from "./types.js";
-
-// ── Memory ──
-
-export interface MemoryStoreInput {
-  actorId: string;
-  content: string;
-  memoryType?: MemoryType;
-  importance?: number;
-  emotionalValence?: number;
-  tags?: string[];
-  embedding?: number[];
-  sourceId?: string;
-  metadata?: Record<string, unknown>;
-  expiresAt?: Date;
-  onConflict?: "append";
-  /** Pre-assigned ID. When set, the storage adapter uses it instead of generating one. */
-  id?: string;
-}
-
-export interface MemoryStore {
-  store(input: MemoryStoreInput): Promise<Memory>;
-  storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]>;
-  get(id: string): Promise<Memory | null>;
-  delete(id: string): Promise<void>;
-  deleteMany(ids: string[]): Promise<number>;
-  touch(id: string): Promise<void>;
-  count(filter?: MemoryCountFilter): Promise<number>;
-  retrieve(query: MemoryRetrieveQuery): Promise<Memory[]>;
-  compileContext(options: ContextOptions): Promise<import("./types.js").CompiledContext>;
-  summarize(options: SummarizeOptions, onError?: (err: Error) => void): Promise<{ summary: Memory; deletedCount: number }>;
-  prune(strategy: PruneStrategy): Promise<{ pruned: string[]; count: number }>;
-  dryRunPrune(strategy: PruneStrategy): Promise<{ wouldPrune: string[]; count: number }>;
-  export(): Promise<Memory[]>;
-}
-
-export interface MemoryCountFilter {
-  actorId?: string;
-  memoryType?: MemoryType;
-  minImportance?: number;
-}
-
-export interface MemoryRetrieveQuery {
-  actorId?: string;
-  query?: string;
-  memoryTypes?: MemoryType[];
-  tags?: string[];
-  limit?: number;
-  strategy?: "semantic" | "hybrid" | "recent" | "important";
-}
-
-export interface ContextOptions {
-  actorId: string;
-  maxTokens?: number;
-  memoryTypes?: MemoryType[];
-}
-
-export interface SummarizeOptions {
-  actorId?: string;
-  olderThan?: Date;
-  skipMostRecent?: number;
-  targetCount?: number;
-  memoryTypes?: MemoryType[];
-  keepOriginals?: boolean;
-}
-
-export interface PruneStrategy {
-  type: "byAge" | "byImportance" | "byCount" | "byType" | "custom";
-  maxAge?: number;
-  minImportance?: number;
-  maxPerActor?: number;
-  memoryTypes?: MemoryType[];
-  /** Custom predicate: return true for memories that should be REMOVED. */
-  shouldRemove?: (memory: Memory) => boolean;
-}
-
-// ── Adapters ──
-
-export interface LLMProvider {
-  complete(request: {
-    system: string;
-    user: string;
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-  }): Promise<{
-    text: string;
-    tokens: { prompt: number; completion: number; total: number };
-  }>;
-  /** Optional streaming variant. Returns an async iterable of text chunks. */
-  completeStream?(request: {
-    system: string;
-    user: string;
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-  }): AsyncIterable<{ text: string; tokens: { prompt: number; completion: number; total: number } }>;
-}
-
-export interface EmbeddingProvider {
-  embed(texts: string[]): Promise<number[][]>;
-  dimensions: number;
-}
-
-export interface StorageProvider {
-  initialize(): Promise<void>;
-  store(memory: MemoryStoreInput): Promise<Memory>;
-  storeBatch(memories: MemoryStoreInput[]): Promise<Memory[]>;
-  get(id: string): Promise<Memory | null>;
-  delete(id: string): Promise<void>;
-  deleteMany(ids: string[]): Promise<number>;
-  /** Update the last-accessed timestamp for a memory without changing its content, id, or createdAt. */
-  touch?(id: string): Promise<void>;
-  retrieve(query: MemoryRetrieveQuery, embedding?: number[]): Promise<Memory[]>;
-  count(filter?: MemoryCountFilter): Promise<number>;
-  close(): Promise<void>;
-}
-
-// ── MemStack Client ──
-
-export interface MemStackConfig {
-  llm: LLMProvider;
-  embedding?: EmbeddingProvider;
-  storage?: StorageProvider;
-  defaults?: {
-    summarizationThreshold?: number;
-    embedOnStore?: boolean;
-    pruneStrategy?: PruneStrategy;
-    pruneInterval?: number;   // Prune every N process() calls. Default: 100.
-    autoImportance?: boolean; // LLM-based importance scoring when importance not provided
-    autoTags?: boolean;       // LLM-based tag extraction when tags not provided
-    summarizationPrompt?: string; // Custom prompt for the summarizer
-  };
-  hooks?: {
-    onMemoryStored?: (memory: Memory) => void;
-    onMemoryPruned?: (ids: string[]) => void;
-    onSummaryCreated?: (summary: Memory, deletedCount: number) => void;
-    onError?: (error: Error, context: string) => void;
-  };
-}
-
-export interface ProcessInput {
-  actorId: string;
-  content: string;
-  memoryType?: MemoryType;
-  importance?: number;
-  emotionalValence?: number;
-  tags?: string[];
-  metadata?: Record<string, unknown>;
-  expiresAt?: Date;
-  onConflict?: "append";
-}
-
-export type { ProcessResult };

package/src/memory/ContextCompiler.ts

@@ -1,158 +0,0 @@
-import type { Memory, CompiledContext } from "../types.js";
-import type { ContextOptions } from "../interfaces.js";
-
-export class ContextCompiler {
-  /**
-   * Estimate token count from text using a blended heuristic.
-   * Combines word-based (prose) and character-based (code/json) estimates,
-   * taking the max to handle arbitrary content types.
-   */
-  private estimateTokens(text: string): number {
-    const charEst = Math.ceil(text.length / 4);
-    const words = text.split(/\s+/).filter((w) => w.length > 0);
-    const wordEst = Math.ceil(words.length * 1.3);
-    return Math.max(charEst, Math.max(1, wordEst));
-  }
-
-  /**
-   * Truncate text to fit within a token budget, preserving whole words.
-   * Appends "..." when content is cut. Falls back to character-based
-   * truncation for text with few/no word boundaries.
-   */
-  private truncateToTokens(text: string, maxTokens: number): string {
-    if (this.estimateTokens(text) <= maxTokens) return text;
-
-    const words = text.split(/\s+/);
-    const targetWords = Math.max(1, Math.floor(maxTokens / 1.3));
-    let currentTokens = 0;
-    let i = 0;
-    for (; i < words.length && i < targetWords; i++) {
-      currentTokens += this.estimateTokens(words[i]);
-      if (currentTokens > maxTokens) break;
-    }
-    if (i >= words.length) return text;
-    if (i > 0) return words.slice(0, i).join(" ") + "...";
-
-    // Single long word (e.g., JSON): fall back to character-based cut
-    const charLimit = maxTokens * 4;
-    return text.slice(0, charLimit) + "...";
-  }
-
-  compile(memories: Memory[], options: ContextOptions): CompiledContext {
-    const maxTokens = options.maxTokens ?? 2000;
-
-    const relevant = memories.filter((m) => {
-      if (options.memoryTypes && options.memoryTypes.length > 0) {
-        return options.memoryTypes.includes(m.memoryType);
-      }
-      return true;
-    });
-
-    const sortedRecent = [...relevant].sort(
-      (a, b) => b.createdAt.getTime() - a.createdAt.getTime()
-    );
-
-    const sortedImportant = this.deduplicate(
-      [...relevant]
-        .filter((m) => m.importance >= 0.5)
-        .sort((a, b) => b.importance - a.importance)
-    );
-
-    const { recentMemories, importantMemories, systemPrompt } =
-      this.assembleTokenBudgeted(sortedRecent, sortedImportant, maxTokens);
-
-    const tokenEstimate = this.estimateTokens(systemPrompt);
-
-    return { systemPrompt, recentMemories, importantMemories, tokenEstimate };
-  }
-
-  private assembleTokenBudgeted(
-    recent: Memory[],
-    important: Memory[],
-    maxTokens: number
-  ): { recentMemories: Memory[]; importantMemories: Memory[]; systemPrompt: string } {
-    const includedImportant: Memory[] = [];
-    const includedRecent: Memory[] = [];
-    const seen = new Set<string>();
-    let usedTokens = 0;
-
-    // Add important memories first (signal over recency)
-    for (const m of important) {
-      if (seen.has(m.id)) continue;
-      const prefix = `- `;
-      const suffix = ` (${m.memoryType}, importance: ${m.importance.toFixed(2)})\n`;
-      const overhead = this.estimateTokens(prefix + suffix);
-      let tokens = this.estimateTokens(m.content) + overhead;
-      const remaining = Math.floor(maxTokens * 0.6) - usedTokens;
-      if (remaining <= 0) break;
-      if (tokens > remaining) {
-        const contentBudget = Math.max(0, remaining - overhead);
-        if (contentBudget > 0) {
-          const truncatedContent = this.truncateToTokens(m.content, contentBudget);
-          includedImportant.push({ ...m, content: truncatedContent });
-          tokens = this.estimateTokens(truncatedContent) + overhead;
-          usedTokens += tokens;
-          seen.add(m.id);
-        }
-      } else {
-        includedImportant.push(m);
-        usedTokens += tokens;
-        seen.add(m.id);
-      }
-    }
-
-    // Add recent memories until budget is full
-    for (const m of recent) {
-      if (seen.has(m.id)) continue;
-      const prefix = `- `;
-      const suffix = `\n`;
-      const overhead = this.estimateTokens(prefix + suffix);
-      let tokens = this.estimateTokens(m.content) + overhead;
-      const remaining = maxTokens - usedTokens;
-      if (remaining <= 0) break;
-      if (tokens > remaining) {
-        const contentBudget = Math.max(0, remaining - overhead);
-        if (contentBudget > 0) {
-          const truncatedContent = this.truncateToTokens(m.content, contentBudget);
-          includedRecent.push({ ...m, content: truncatedContent });
-          tokens = this.estimateTokens(truncatedContent) + overhead;
-          usedTokens += tokens;
-          seen.add(m.id);
-        }
-      } else {
-        includedRecent.push(m);
-        usedTokens += tokens;
-        seen.add(m.id);
-      }
-    }
-
-    const parts: string[] = [];
-    if (includedImportant.length > 0) {
-      parts.push("## Important Memories");
-      for (const m of includedImportant) {
-        parts.push(`- ${m.content} (${m.memoryType}, importance: ${m.importance.toFixed(2)})`);
-      }
-    }
-    if (includedRecent.length > 0) {
-      parts.push("\n## Recent Interactions");
-      for (const m of includedRecent) {
-        parts.push(`- ${m.content}`);
-      }
-    }
-
-    return { recentMemories: includedRecent, importantMemories: includedImportant, systemPrompt: parts.join("\n") };
-  }
-
-  private deduplicate(memories: Memory[]): Memory[] {
-    const seen = new Set<string>();
-    const result: Memory[] = [];
-    for (const m of memories) {
-      const key = m.content.toLowerCase().trim();
-      if (!seen.has(key)) {
-        seen.add(key);
-        result.push(m);
-      }
-    }
-    return result;
-  }
-}