@memstack/core 0.2.0 → 0.5.0

package/src/adapters/llm/openai.ts

@@ -1,178 +0,0 @@
-import type { LLMProvider } from "../../interfaces.js";
-import { MemStackError } from "../../errors.js";
-
-export interface OpenAILLMConfig {
-  apiKey: string;
-  baseURL?: string;
-  defaultModel?: string;
-  defaultTemperature?: number;
-  defaultMaxTokens?: number;
-}
-
-export class OpenAILLMAdapter implements LLMProvider {
-  private apiKey: string;
-  private baseURL: string;
-  private defaultModel: string;
-  private defaultTemperature: number;
-  private defaultMaxTokens: number;
-
-  constructor(config: OpenAILLMConfig) {
-    this.apiKey = config.apiKey;
-    this.baseURL = config.baseURL ?? "https://api.openai.com/v1";
-    this.defaultModel = config.defaultModel ?? "gpt-4o-mini";
-    this.defaultTemperature = config.defaultTemperature ?? 0.7;
-    this.defaultMaxTokens = config.defaultMaxTokens ?? 1024;
-  }
-
-  async complete(request: {
-    system: string;
-    user: string;
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-  }): Promise<{ text: string; tokens: { prompt: number; completion: number; total: number } }> {
-    const model = request.model ?? this.defaultModel;
-    const temperature = request.temperature ?? this.defaultTemperature;
-    const maxTokens = request.maxTokens ?? this.defaultMaxTokens;
-
-    try {
-      const response = await fetch(`${this.baseURL}/chat/completions`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`,
-        },
-        body: JSON.stringify({
-          model,
-          messages: [
-            { role: "system", content: request.system },
-            { role: "user", content: request.user },
-          ],
-          temperature,
-          max_tokens: maxTokens,
-        }),
-      });
-
-      if (!response.ok) {
-        const err = await response.text();
-        throw new MemStackError("LLM_ERROR", `OpenAI API error: ${response.status} ${err}`, {
-          retryable: response.status >= 500,
-        });
-      }
-
-      const data = (await response.json()) as {
-        choices: { message: { content: string } }[];
-        usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
-      };
-
-      return {
-        text: data.choices[0]?.message?.content ?? "",
-        tokens: {
-          prompt: data.usage?.prompt_tokens ?? 0,
-          completion: data.usage?.completion_tokens ?? 0,
-          total: data.usage?.total_tokens ?? 0,
-        },
-      };
-    } catch (err) {
-      if (err instanceof MemStackError) throw err;
-      throw new MemStackError("LLM_ERROR", `LLM request failed: ${err instanceof Error ? err.message : String(err)}`, {
-        retryable: true,
-      });
-    }
-  }
-
-  async *completeStream(request: {
-    system: string;
-    user: string;
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-  }): AsyncIterable<{ text: string; tokens: { prompt: number; completion: number; total: number } }> {
-    const model = request.model ?? this.defaultModel;
-    const temperature = request.temperature ?? this.defaultTemperature;
-    const maxTokens = request.maxTokens ?? this.defaultMaxTokens;
-
-    let response: Response;
-    try {
-      response = await fetch(`${this.baseURL}/chat/completions`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`,
-        },
-        body: JSON.stringify({
-          model,
-          messages: [
-            { role: "system", content: request.system },
-            { role: "user", content: request.user },
-          ],
-          temperature,
-          max_tokens: maxTokens,
-          stream: true,
-          stream_options: { include_usage: true },
-        }),
-      });
-    } catch (err) {
-      throw new MemStackError("LLM_ERROR", `OpenAI streaming request failed: ${err instanceof Error ? err.message : String(err)}`, {
-        retryable: true,
-      });
-    }
-
-    if (!response.ok) {
-      const err = await response.text();
-      throw new MemStackError("LLM_ERROR", `OpenAI streaming error: ${response.status} ${err}`, {
-        retryable: response.status >= 500,
-      });
-    }
-
-    const reader = response.body?.getReader();
-    if (!reader) throw new MemStackError("LLM_ERROR", "No response body for streaming");
-
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let promptTokens = 0;
-    let completionTokens = 0;
-
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed || !trimmed.startsWith("data: ")) continue;
-          const data = trimmed.slice(6);
-          if (data === "[DONE]") continue;
-
-          try {
-            const parsed = JSON.parse(data) as {
-              choices?: { delta?: { content?: string } }[];
-              usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
-            };
-
-            const content = parsed.choices?.[0]?.delta?.content ?? "";
-            if (parsed.usage) {
-              promptTokens = parsed.usage.prompt_tokens;
-              completionTokens = parsed.usage.completion_tokens;
-            }
-
-            if (content) {
-              yield {
-                text: content,
-                tokens: { prompt: promptTokens, completion: completionTokens, total: promptTokens + completionTokens },
-              };
-            }
-          } catch {
-            // Skip unparseable chunks
-          }
-        }
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
-}

package/src/adapters/storage/disk.ts

@@ -1,334 +0,0 @@
-import { mkdir, readFile, writeFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import type { Memory, MemoryType } from "../../types.js";
-import type { StorageProvider, MemoryStoreInput, MemoryRetrieveQuery, MemoryCountFilter } from "../../interfaces.js";
-import { storageError, notFound } from "../../errors.js";
-
-interface MemoryRecord extends Memory {
-  _touchedAt: string;
-}
-
-export interface DiskStorageConfig {
-  /** Directory to store memory files. Default: "./memstack-data" */
-  storageDir?: string;
-}
-
-export class DiskStorage implements StorageProvider {
-  private dir: string;
-  private _writeLocks = new Map<string, Promise<void>>();
-
-  constructor(config: DiskStorageConfig = {}) {
-    this.dir = config.storageDir ?? "./memstack-data";
-  }
-
-  async initialize(): Promise<void> {
-    await mkdir(this.dir, { recursive: true });
-  }
-
-  generateId(): string {
-    return `mem_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`;
-  }
-
-  async store(input: MemoryStoreInput): Promise<Memory> {
-    const now = new Date();
-    const memory: MemoryRecord = {
-      id: input.id ?? this.generateId(),
-      actorId: input.actorId,
-      memoryType: (input.memoryType ?? "interaction") as MemoryType,
-      content: input.content,
-      importance: input.importance ?? 0.5,
-      emotionalValence: input.emotionalValence ?? 0,
-      tags: input.tags ?? [],
-      embedding: input.embedding,
-      sourceId: input.sourceId,
-      metadata: input.metadata ?? {},
-      expiresAt: input.expiresAt,
-      createdAt: now,
-      _touchedAt: now.toISOString(),
-    };
-
-    await this._withWriteLock(input.actorId, async () => {
-      const records = await this._readFile(input.actorId);
-      const existingIdx = records.findIndex((r) => r.id === memory.id);
-      if (existingIdx !== -1) {
-        records[existingIdx] = memory;
-      } else {
-        records.push(memory);
-      }
-      await this._writeFile(input.actorId, records);
-    });
-
-    return this._toExternal(memory);
-  }
-
-  async storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]> {
-    const byActor = new Map<string, MemoryRecord[]>();
-    const now = new Date();
-    const all: MemoryRecord[] = [];
-
-    for (const input of inputs) {
-      const memory: MemoryRecord = {
-        id: input.id ?? this.generateId(),
-        actorId: input.actorId,
-        memoryType: (input.memoryType ?? "interaction") as MemoryType,
-        content: input.content,
-        importance: input.importance ?? 0.5,
-        emotionalValence: input.emotionalValence ?? 0,
-        tags: input.tags ?? [],
-        embedding: input.embedding,
-        sourceId: input.sourceId,
-        metadata: input.metadata ?? {},
-        expiresAt: input.expiresAt,
-        createdAt: now,
-        _touchedAt: now.toISOString(),
-      };
-      all.push(memory);
-      const group = byActor.get(input.actorId) ?? [];
-      group.push(memory);
-      byActor.set(input.actorId, group);
-    }
-
-    for (const [actorId, group] of byActor) {
-      await this._withWriteLock(actorId, async () => {
-        const existing = await this._readFile(actorId);
-        for (const mem of group) {
-          const existingIdx = existing.findIndex((r) => r.id === mem.id);
-          if (existingIdx !== -1) {
-            existing[existingIdx] = mem;
-          } else {
-            existing.push(mem);
-          }
-        }
-        await this._writeFile(actorId, existing);
-      });
-    }
-
-    return all.map((m) => this._toExternal(m));
-  }
-
-  async get(id: string): Promise<Memory | null> {
-    const actorIds = await this._listActors();
-    for (const actorId of actorIds) {
-      const records = await this._readFile(actorId);
-      const record = records.find((r) => r.id === id);
-      if (record) {
-        if (record.expiresAt && new Date(record.expiresAt) <= new Date()) return null;
-        return this._toExternal(record);
-      }
-    }
-    return null;
-  }
-
-  async delete(id: string): Promise<void> {
-    const actorIds = await this._listActors();
-    for (const actorId of actorIds) {
-      const records = await this._readFile(actorId);
-      const index = records.findIndex((r) => r.id === id);
-      if (index !== -1) {
-        await this._withWriteLock(actorId, async () => {
-          const fresh = await this._readFile(actorId);
-          const i = fresh.findIndex((r) => r.id === id);
-          if (i !== -1) {
-            fresh.splice(i, 1);
-            await this._writeFile(actorId, fresh);
-          }
-        });
-        return;
-      }
-    }
-    throw notFound("Memory", id);
-  }
-
-  async deleteMany(ids: string[]): Promise<number> {
-    const idSet = new Set(ids);
-    let count = 0;
-    const actorIds = await this._listActors();
-
-    for (const actorId of actorIds) {
-      await this._withWriteLock(actorId, async () => {
-        const records = await this._readFile(actorId);
-        const before = records.length;
-        const filtered = records.filter((r) => !idSet.has(r.id));
-        count += before - filtered.length;
-        if (before !== filtered.length) {
-          await this._writeFile(actorId, filtered);
-        }
-      });
-    }
-
-    return count;
-  }
-
-  async retrieve(query: MemoryRetrieveQuery, _embedding?: number[]): Promise<Memory[]> {
-    const actorIds = query.actorId ? [query.actorId] : await this._listActors();
-    let results: MemoryRecord[] = [];
-
-    for (const actorId of actorIds) {
-      let records = await this._readFile(actorId);
-      const now = new Date();
-      records = records.filter((r) => !r.expiresAt || new Date(r.expiresAt) > now);
-
-      if (query.memoryTypes && query.memoryTypes.length > 0) {
-        records = records.filter((r) => query.memoryTypes!.includes(r.memoryType));
-      }
-      if (query.tags && query.tags.length > 0) {
-        records = records.filter((r) => r.tags?.some((t) => query.tags!.includes(t)));
-      }
-      if (query.query) {
-        const q = query.query.toLowerCase();
-        records = records.filter((r) => r.content.toLowerCase().includes(q));
-      }
-
-      results.push(...records);
-    }
-
-    switch (query.strategy) {
-      case "recent":
-        results.sort((a, b) => new Date(b._touchedAt).getTime() - new Date(a._touchedAt).getTime());
-        break;
-      case "important":
-        results.sort((a, b) => b.importance - a.importance);
-        break;
-      case "hybrid":
-      case "semantic":
-      default:
-        results.sort(
-          (a, b) =>
-            b.importance - a.importance || new Date(b._touchedAt).getTime() - new Date(a._touchedAt).getTime()
-        );
-        break;
-    }
-
-    // Touch records on retrieval
-    const nowStr = new Date().toISOString();
-    const toTouch = results.slice(0, query.limit ?? 10);
-    const touchedActors = new Set<string>();
-    for (const r of toTouch) {
-      r._touchedAt = nowStr;
-      touchedActors.add(r.actorId);
-    }
-    // Persist touches back to disk
-    for (const actorId of touchedActors) {
-      await this._withWriteLock(actorId, async () => {
-        const records = await this._readFile(actorId);
-        let changed = false;
-        for (const r of records) {
-          const touched = toTouch.find((t) => t.id === r.id);
-          if (touched) { r._touchedAt = nowStr; changed = true; }
-        }
-        if (changed) await this._writeFile(actorId, records);
-      });
-    }
-
-    const limit = query.limit ?? 10;
-    return results.slice(0, limit).map((r) => this._toExternal(r));
-  }
-
-  async count(filter?: MemoryCountFilter): Promise<number> {
-    const actorIds = filter?.actorId ? [filter.actorId] : await this._listActors();
-    let total = 0;
-    const now = new Date();
-
-    for (const actorId of actorIds) {
-      let records = await this._readFile(actorId);
-      records = records.filter((r) => !r.expiresAt || new Date(r.expiresAt) > now);
-
-      if (filter?.memoryType) {
-        records = records.filter((r) => r.memoryType === filter.memoryType);
-      }
-      if (filter?.minImportance !== undefined) {
-        records = records.filter((r) => r.importance >= filter.minImportance!);
-      }
-      total += records.length;
-    }
-
-    return total;
-  }
-
-  async touch(id: string): Promise<void> {
-    const actorIds = await this._listActors();
-    for (const actorId of actorIds) {
-      const records = await this._readFile(actorId);
-      const found = records.find((r) => r.id === id);
-      if (found) {
-        const nowStr = new Date().toISOString();
-        await this._withWriteLock(actorId, async () => {
-          const fresh = await this._readFile(actorId);
-          const match = fresh.find((r) => r.id === id);
-          if (match) {
-            match._touchedAt = nowStr;
-            await this._writeFile(actorId, fresh);
-          }
-        });
-        return;
-      }
-    }
-    throw notFound("Memory", id);
-  }
-
-  async close(): Promise<void> {
-    this._writeLocks.clear();
-  }
-
-  // ── Internal ──
-
-  private _filePath(actorId: string): string {
-    const safe = actorId.replace(/[^a-zA-Z0-9_\-.,@]/g, "_");
-    return join(this.dir, `${safe}.json`);
-  }
-
-  private async _readFile(actorId: string): Promise<MemoryRecord[]> {
-    try {
-      const raw = await readFile(this._filePath(actorId), "utf-8");
-      const parsed = JSON.parse(raw);
-      return Array.isArray(parsed) ? (parsed as MemoryRecord[]) : [];
-    } catch (err: unknown) {
-      if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
-      throw storageError(`Failed to read memories for actor ${actorId}: ${(err as Error).message}`);
-    }
-  }
-
-  private async _writeFile(actorId: string, records: MemoryRecord[]): Promise<void> {
-    try {
-      await writeFile(this._filePath(actorId), JSON.stringify(records, null, 2), "utf-8");
-    } catch (err) {
-      throw storageError(`Failed to write memories for actor ${actorId}: ${(err as Error).message}`);
-    }
-  }
-
-  private async _withWriteLock(actorId: string, fn: () => Promise<void>): Promise<void> {
-    const prev = this._writeLocks.get(actorId) ?? Promise.resolve();
-    let resolve!: () => void;
-    const next = new Promise<void>((r) => { resolve = r; });
-    this._writeLocks.set(actorId, next);
-    await prev;
-    try {
-      await fn();
-    } finally {
-      resolve();
-      // Clean up: only remove this entry if it hasn't been replaced by a newer lock
-      if (this._writeLocks.get(actorId) === next) {
-        this._writeLocks.delete(actorId);
-      }
-    }
-  }
-
-  private async _listActors(): Promise<string[]> {
-    try {
-      const entries = await readdir(this.dir);
-      return entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5));
-    } catch (err: unknown) {
-      if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
-      throw storageError(`Failed to list actors: ${(err as Error).message}`);
-    }
-  }
-
-  private _toExternal(record: MemoryRecord): Memory {
-    const { _touchedAt: _, ...rest } = record;
-    return {
-      ...rest,
-      createdAt: new Date(record.createdAt),
-      expiresAt: record.expiresAt ? new Date(record.expiresAt) : undefined,
-    };
-  }
-}

package/src/adapters/storage/memory.ts

@@ -1,147 +0,0 @@
-import type { Memory, MemoryType } from "../../types.js";
-import type { StorageProvider, MemoryStoreInput, MemoryRetrieveQuery, MemoryCountFilter } from "../../interfaces.js";
-import { storageError, notFound } from "../../errors.js";
-
-interface MemoryRecord extends Memory {
-  _touchedAt: Date;
-}
-
-export class InMemoryStorage implements StorageProvider {
-  private memories: Map<string, MemoryRecord> = new Map();
-
-  async initialize(): Promise<void> {}
-
-  generateId(): string {
-    return `mem_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`;
-  }
-
-  async store(input: MemoryStoreInput): Promise<Memory> {
-    const now = new Date();
-    const memory: MemoryRecord = {
-      id: input.id ?? this.generateId(),
-      actorId: input.actorId,
-      memoryType: (input.memoryType ?? "interaction") as MemoryType,
-      content: input.content,
-      importance: input.importance ?? 0.5,
-      emotionalValence: input.emotionalValence ?? 0,
-      tags: input.tags ?? [],
-      embedding: input.embedding,
-      sourceId: input.sourceId,
-      metadata: input.metadata ?? {},
-      expiresAt: input.expiresAt,
-      createdAt: now,
-      _touchedAt: now,
-    };
-    this.memories.set(memory.id, memory);
-    return memory;
-  }
-
-  async storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]> {
-    const results: Memory[] = [];
-    for (const input of inputs) {
-      results.push(await this.store(input));
-    }
-    return results;
-  }
-
-  async get(id: string): Promise<Memory | null> {
-    const memory = this.memories.get(id);
-    if (!memory) return null;
-    if (memory.expiresAt && memory.expiresAt <= new Date()) {
-      this.memories.delete(id);
-      return null;
-    }
-    return memory;
-  }
-
-  async delete(id: string): Promise<void> {
-    if (!this.memories.has(id)) throw notFound("Memory", id);
-    this.memories.delete(id);
-  }
-
-  async deleteMany(ids: string[]): Promise<number> {
-    let count = 0;
-    for (const id of ids) {
-      if (this.memories.has(id)) {
-        this.memories.delete(id);
-        count++;
-      }
-    }
-    return count;
-  }
-
-  async retrieve(query: MemoryRetrieveQuery, _embedding?: number[]): Promise<Memory[]> {
-    let results = Array.from(this.memories.values());
-
-    // Filter out expired
-    const now = new Date();
-    results = results.filter((m) => !m.expiresAt || m.expiresAt > now);
-
-    if (query.actorId) {
-      results = results.filter((m) => m.actorId === query.actorId);
-    }
-    if (query.memoryTypes && query.memoryTypes.length > 0) {
-      results = results.filter((m) => query.memoryTypes!.includes(m.memoryType));
-    }
-    if (query.tags && query.tags.length > 0) {
-      results = results.filter((m) => m.tags?.some((t) => query.tags!.includes(t)));
-    }
-    if (query.query) {
-      const q = query.query.toLowerCase();
-      results = results.filter((m) => m.content.toLowerCase().includes(q));
-    }
-
-    switch (query.strategy) {
-      case "recent":
-        results.sort((a, b) => b._touchedAt.getTime() - a._touchedAt.getTime());
-        break;
-      case "important":
-        results.sort((a, b) => b.importance - a.importance);
-        break;
-      case "hybrid":
-      case "semantic":
-      default:
-        results.sort((a, b) => b.importance - a.importance || b._touchedAt.getTime() - a._touchedAt.getTime());
-        break;
-    }
-
-    // Touch records on retrieval (for recency tracking in context assembly)
-    for (const r of results.slice(0, query.limit ?? 10)) {
-      r._touchedAt = new Date();
-    }
-
-    const limit = query.limit ?? 10;
-    return results.slice(0, limit);
-  }
-
-  async count(filter?: MemoryCountFilter): Promise<number> {
-    const now = new Date();
-    let results = Array.from(this.memories.values())
-      .filter((m) => !m.expiresAt || m.expiresAt > now);
-
-    if (filter?.actorId) {
-      results = results.filter((m) => m.actorId === filter.actorId);
-    }
-    if (filter?.memoryType) {
-      results = results.filter((m) => m.memoryType === filter.memoryType);
-    }
-    if (filter?.minImportance !== undefined) {
-      results = results.filter((m) => m.importance >= filter.minImportance!);
-    }
-    return results.length;
-  }
-
-  async touch(id: string): Promise<void> {
-    const memory = this.memories.get(id);
-    if (!memory) throw notFound("Memory", id);
-    memory._touchedAt = new Date();
-  }
-
-  async close(): Promise<void> {
-    this.memories.clear();
-  }
-
-  getAllMemories(): Memory[] {
-    return Array.from(this.memories.values());
-  }
-}