@memstack/core 0.2.0 → 0.4.0

package/src/memory/MemoryStore.ts

@@ -1,266 +0,0 @@
-import type { Memory, CompiledContext } from "../types.js";
-import type {
-  StorageProvider,
-  EmbeddingProvider,
-  LLMProvider,
-  MemoryStoreInput,
-  MemoryRetrieveQuery,
-  MemoryCountFilter,
-  ContextOptions,
-  SummarizeOptions,
-  PruneStrategy,
-} from "../interfaces.js";
-import { Summarizer } from "./Summarizer.js";
-import { Pruner } from "./Pruner.js";
-import { ContextCompiler } from "./ContextCompiler.js";
-import { notFound, validationError } from "../errors.js";
-
-export interface MemoryStoreConfig {
-  storage: StorageProvider;
-  embedding?: EmbeddingProvider;
-  llm?: LLMProvider;
-  embedOnStore?: boolean;
-  summarizationPrompt?: string;
-}
-
-const EMBEDDING_BATCH_SIZE = 2048;
-
-export class MemoryStore {
-  private storage: StorageProvider;
-  private embedding?: EmbeddingProvider;
-  private summarizer?: Summarizer;
-  private pruner: Pruner;
-  private compiler: ContextCompiler;
-  private embedOnStore: boolean;
-
-  constructor(config: MemoryStoreConfig) {
-    this.storage = config.storage;
-    this.embedding = config.embedding;
-    this.embedOnStore = config.embedOnStore ?? true;
-    if (config.llm) {
-      this.summarizer = new Summarizer(config.llm, config.summarizationPrompt);
-    }
-    this.pruner = new Pruner();
-    this.compiler = new ContextCompiler();
-  }
-
-  async store(input: MemoryStoreInput): Promise<Memory> {
-    // On conflict "append": deduplicate by content hash, update existing instead
-    if (input.onConflict === "append") {
-      const hash = this._hashContent(input.actorId, input.content);
-      const existing = await this.storage.retrieve({ actorId: input.actorId, limit: 1000 });
-      const match = existing.find(
-        (m) => this._hashContent(m.actorId, m.content) === hash
-      );
-      if (match) {
-        // Upsert: update existing instead of creating duplicate
-        const mergedTags = [...new Set([...(match.tags ?? []), ...(input.tags ?? [])])];
-        const updated = await this.storage.store({
-          id: match.id,
-          actorId: match.actorId,
-          content: match.content,
-          memoryType: match.memoryType,
-          importance: input.importance ?? match.importance,
-          emotionalValence: input.emotionalValence ?? match.emotionalValence,
-          tags: mergedTags,
-          embedding: match.embedding,
-          sourceId: input.sourceId ?? match.sourceId,
-          metadata: { ...match.metadata, ...input.metadata },
-          expiresAt: input.expiresAt ?? match.expiresAt,
-        });
-        return updated;
-      }
-    }
-
-    let withEmbedding = input;
-    if (this.embedding && this.embedOnStore) {
-      const embeddings = await this.embedding.embed([input.content]);
-      withEmbedding = { ...input, embedding: embeddings[0] };
-    }
-    const { onConflict: _, ...clean } = withEmbedding;
-    return this.storage.store(clean);
-  }
-
-  async storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]> {
-    // Handle onConflict: "append" inputs individually (they need dedup checks)
-    const appendInputs = inputs.filter((i) => i.onConflict === "append");
-    const normalInputs = inputs.filter((i) => i.onConflict !== "append");
-
-    const results: Memory[] = [];
-
-    // Process append inputs one-by-one through store() for dedup
-    for (const input of appendInputs) {
-      results.push(await this.store(input));
-    }
-
-    if (normalInputs.length === 0) return results;
-
-    if (this.embedding && this.embedOnStore) {
-      for (let i = 0; i < normalInputs.length; i += EMBEDDING_BATCH_SIZE) {
-        const batch = normalInputs.slice(i, i + EMBEDDING_BATCH_SIZE);
-        const texts = batch.map((inp) => inp.content);
-        const embeddings = await this.embedding!.embed(texts);
-        const enriched = batch.map((input, j) => ({ ...input, embedding: embeddings[j] }));
-        const stored = await this.storage.storeBatch(enriched);
-        results.push(...stored);
-      }
-    } else {
-      const stored = await this.storage.storeBatch(normalInputs);
-      results.push(...stored);
-    }
-
-    return results;
-  }
-
-  async get(id: string): Promise<Memory | null> {
-    return this.storage.get(id);
-  }
-
-  async delete(id: string): Promise<void> {
-    return this.storage.delete(id);
-  }
-
-  async deleteMany(ids: string[]): Promise<number> {
-    return this.storage.deleteMany(ids);
-  }
-
-  async touch(id: string): Promise<void> {
-    const memory = await this.storage.get(id);
-    if (!memory) throw notFound("Memory", id);
-    if (this.storage.touch) {
-      return this.storage.touch(id);
-    }
-    // legacy fallback: storage doesn't support in-place touch
-    await this.storage.delete(id);
-    await this.storage.store({
-      actorId: memory.actorId,
-      content: memory.content,
-      memoryType: memory.memoryType,
-      importance: memory.importance,
-      emotionalValence: memory.emotionalValence,
-      tags: memory.tags,
-      embedding: memory.embedding,
-      sourceId: memory.sourceId,
-      metadata: memory.metadata,
-      expiresAt: memory.expiresAt,
-    });
-  }
-
-  async count(filter?: MemoryCountFilter): Promise<number> {
-    return this.storage.count(filter);
-  }
-
-  async retrieve(query: MemoryRetrieveQuery): Promise<Memory[]> {
-    let embedding: number[] | undefined;
-    if (this.embedding && query.query && (query.strategy === "semantic" || query.strategy === "hybrid")) {
-      const vecs = await this.embedding.embed([query.query]);
-      embedding = vecs[0];
-    }
-    return this.storage.retrieve(query, embedding);
-  }
-
-  async compileContext(options: ContextOptions): Promise<CompiledContext> {
-    const maxTokens = options.maxTokens ?? 2000;
-    // Fetch up to 50 memories; compiler will truncate to meet token budget
-    const memories = await this.storage.retrieve({ actorId: options.actorId, limit: 50 });
-    return this.compiler.compile(memories, { ...options, maxTokens });
-  }
-
-  async summarize(
-    options: SummarizeOptions,
-    onError?: (err: Error) => void
-  ): Promise<{ summary: Memory; deletedCount: number }> {
-    if (!this.summarizer) {
-      throw validationError("No LLM configured for summarization");
-    }
-
-    const allMemories = await this.storage.retrieve({
-      actorId: options.actorId,
-      memoryTypes: options.memoryTypes ?? ["interaction"],
-      limit: 1000,
-      strategy: "recent",
-    });
-
-    let toSummarize = allMemories;
-    if (options.olderThan) {
-      toSummarize = toSummarize.filter((m) => m.createdAt < options.olderThan!);
-    }
-    if (options.skipMostRecent) {
-      // Sort chronological (oldest first), skip most recent N, keep the rest
-      const sorted = [...toSummarize].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
-      toSummarize = sorted.slice(0, Math.max(0, sorted.length - options.skipMostRecent));
-    }
-    if (options.targetCount && toSummarize.length > options.targetCount) {
-      // Keep only the oldest targetCount (most stale, best to summarize)
-      const sorted = [...toSummarize].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
-      toSummarize = sorted.slice(0, options.targetCount);
-    }
-
-    if (toSummarize.length === 0) {
-      throw validationError("No memories to summarize");
-    }
-
-    let summaryContent: string;
-    try {
-      const result = await this.summarizer.summarize(toSummarize, options);
-      summaryContent = result.summaryContent;
-    } catch (err) {
-      onError?.(err instanceof Error ? err : new Error(String(err)));
-      throw err;
-    }
-
-    const summary: Memory = await this.storage.store({
-      actorId: options.actorId ?? toSummarize[0].actorId,
-      content: summaryContent,
-      memoryType: "summary",
-      importance: Math.max(...toSummarize.map((m) => m.importance)),
-      emotionalValence:
-        toSummarize.reduce((sum, m) => sum + m.emotionalValence, 0) / toSummarize.length,
-      tags: ["summary"],
-      sourceId: toSummarize[0].id,
-    });
-
-    let deletedCount = 0;
-    if (!options.keepOriginals) {
-      const ids = toSummarize.map((m) => m.id);
-      deletedCount = await this.storage.deleteMany(ids);
-    }
-
-    return { summary, deletedCount };
-  }
-
-  async prune(strategy: PruneStrategy): Promise<{ pruned: string[]; count: number }> {
-    const allMemories = await this.storage.retrieve({ limit: 10000 });
-    const kept = this.pruner.execute(allMemories, strategy);
-    const keptIds = new Set(kept.map((k) => k.id));
-    const prunedIds = allMemories.filter((m) => !keptIds.has(m.id)).map((m) => m.id);
-    let count = 0;
-    if (prunedIds.length > 0) {
-      count = await this.storage.deleteMany(prunedIds);
-    }
-    return { pruned: prunedIds, count };
-  }
-
-  async dryRunPrune(strategy: PruneStrategy): Promise<{ wouldPrune: string[]; count: number }> {
-    const allMemories = await this.storage.retrieve({ limit: 10000 });
-    const kept = this.pruner.execute(allMemories, strategy);
-    const keptIds = new Set(kept.map((k) => k.id));
-    const wouldPrune = allMemories.filter((m) => !keptIds.has(m.id)).map((m) => m.id);
-    return { wouldPrune, count: wouldPrune.length };
-  }
-
-  async export(): Promise<Memory[]> {
-    return this.storage.retrieve({ limit: 100000 });
-  }
-
-  private _hashContent(actorId: string, content: string): string {
-    const normalized = `${actorId}::${content.toLowerCase().trim()}`;
-    // FNV-1a 64-bit — fast, low collision probability for content dedup
-    let hash = 14695981039346656037n; // FNV offset basis
-    for (let i = 0; i < normalized.length; i++) {
-      hash ^= BigInt(normalized.charCodeAt(i));
-      hash *= 1099511628211n; // FNV prime
-    }
-    return hash.toString(36);
-  }
-}

package/src/memory/Pruner.ts

@@ -1,66 +0,0 @@
-import type { Memory } from "../types.js";
-import type { PruneStrategy } from "../interfaces.js";
-
-export class Pruner {
-  /** Returns memories to KEEP after applying the strategy. */
-  execute(memories: Memory[], strategy: PruneStrategy): Memory[] {
-    switch (strategy.type) {
-      case "byAge":
-        return this.keepByAge(memories, strategy);
-      case "byImportance":
-        return this.keepByImportance(memories, strategy);
-      case "byCount":
-        return this.keepByCount(memories, strategy);
-      case "byType":
-        return this.removeByType(memories, strategy);
-      case "custom":
-        return this.removeCustom(memories, strategy);
-      default:
-        return memories;
-    }
-  }
-
-  dryRun(memories: Memory[], strategy: PruneStrategy): Memory[] {
-    return this.execute(memories, strategy);
-  }
-
-  private keepByAge(memories: Memory[], strategy: PruneStrategy): Memory[] {
-    if (!strategy.maxAge) return memories;
-    const cutoff = Date.now() - strategy.maxAge;
-    return memories.filter((m) => m.createdAt.getTime() >= cutoff);
-  }
-
-  private keepByImportance(memories: Memory[], strategy: PruneStrategy): Memory[] {
-    const threshold = strategy.minImportance ?? 0.5;
-    return memories.filter((m) => m.importance >= threshold);
-  }
-
-  private keepByCount(memories: Memory[], strategy: PruneStrategy): Memory[] {
-    const maxPerActor = strategy.maxPerActor ?? 100;
-    const grouped = new Map<string, Memory[]>();
-    for (const m of memories) {
-      const list = grouped.get(m.actorId) || [];
-      list.push(m);
-      grouped.set(m.actorId, list);
-    }
-
-    const kept: Memory[] = [];
-    for (const [, actorMemories] of grouped) {
-      const sorted = [...actorMemories].sort((a, b) => b.importance - a.importance);
-      kept.push(...sorted.slice(0, maxPerActor));
-    }
-    return kept;
-  }
-
-  /** Remove memories of specified types. Opposite of filtering — removes the matches. */
-  private removeByType(memories: Memory[], strategy: PruneStrategy): Memory[] {
-    if (!strategy.memoryTypes || strategy.memoryTypes.length === 0) return memories;
-    return memories.filter((m) => !strategy.memoryTypes!.includes(m.memoryType));
-  }
-
-  /** Remove memories matching the predicate. Predicate returns true = should be removed. */
-  private removeCustom(memories: Memory[], strategy: PruneStrategy): Memory[] {
-    if (!strategy.shouldRemove) return memories;
-    return memories.filter((m) => !strategy.shouldRemove!(m));
-  }
-}

package/src/memory/Summarizer.ts

@@ -1,46 +0,0 @@
-import type { LLMProvider } from "../interfaces.js";
-import type { Memory } from "../types.js";
-import type { SummarizeOptions } from "../interfaces.js";
-import { MemStackError } from "../errors.js";
-
-export class Summarizer {
-  private llm: LLMProvider;
-  private defaultPrompt: string;
-
-  constructor(llm: LLMProvider, defaultPrompt?: string) {
-    this.llm = llm;
-    this.defaultPrompt = defaultPrompt ??
-      "You are a memory summarizer. Condense the following list of memories into a single, concise summary paragraph that captures the key events, emotional tone, and important details. Write in third person past tense.";
-  }
-
-  async summarize(
-    memories: Memory[],
-    options: SummarizeOptions = {},
-    promptOverride?: string
-  ): Promise<{ summaryContent: string; tokenCount: number }> {
-    if (memories.length === 0) {
-      throw new MemStackError("VALIDATION_ERROR", "No memories to summarize");
-    }
-
-    const sorted = [...memories].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
-    const memoryTexts = sorted.map((m) => `[${m.createdAt.toISOString()}] ${m.content}`);
-
-    const system = promptOverride ?? this.defaultPrompt;
-    const user = memoryTexts.join("\n\n");
-
-    try {
-      const response = await this.llm.complete({ system, user });
-      return {
-        summaryContent: response.text.trim(),
-        tokenCount: response.tokens.total,
-      };
-    } catch (err) {
-      if (err instanceof MemStackError) throw err;
-      throw new MemStackError(
-        "LLM_ERROR",
-        `Summarization failed: ${err instanceof Error ? err.message : String(err)}`,
-        { retryable: true, details: { cause: err instanceof Error ? err.message : String(err) } }
-      );
-    }
-  }
-}

package/src/types.ts

@@ -1,50 +0,0 @@
-// ── Memory ──
-
-export type MemoryType = "interaction" | "summary" | "observation" | "gossip";
-
-export interface Memory {
-  id: string;
-  actorId: string;
-  memoryType: MemoryType;
-  content: string;
-  importance: number;
-  emotionalValence: number;
-  tags: string[];
-  embedding?: number[];
-  sourceId?: string;
-  metadata?: Record<string, unknown>;
-  expiresAt?: Date;
-  createdAt: Date;
-}
-
-// ── Context ──
-
-export interface CompiledContext {
-  systemPrompt: string;
-  recentMemories: Memory[];
-  importantMemories: Memory[];
-  tokenEstimate: number;
-}
-
-// ── Process Result ──
-
-export interface ProcessResult {
-  memory: Memory;
-  summaryCreated?: Memory;
-}
-
-// ── Snapshot ──
-
-export interface MemStackSnapshot {
-  version: 1;
-  memories: Memory[];
-  exportedAt: string;
-}
-
-// ── Health ──
-
-export interface HealthStatus {
-  storage: boolean;
-  llm: boolean;
-  embedding: boolean;
-}