Memstack

import { MemStack, OpenAILLMAdapter, OpenAIEmbeddingAdapter, InMemoryStorageAdapter } from "@memstack/core";
const llm = new OpenAILLMAdapter({ apiKey: process.env.OPENAI_API_KEY! });
const memstack = new MemStack({  llm,  embedding: new OpenAIEmbeddingAdapter({ apiKey: process.env.OPENAI_API_KEY! }),  storage: new InMemoryStorageAdapter(),});

import { MemStack, OpenAILLMAdapter, InMemoryStorageAdapter } from "@memstack/core";
const llm = new OpenAILLMAdapter({  apiKey: process.env.DEEPSEEK_API_KEY!,  baseURL: "https://api.deepseek.com/v1",  defaultModel: "deepseek-flash",});
const memstack = new MemStack({  llm,  storage: new InMemoryStorageAdapter(),  // No embedding adapter — retrieval uses keyword matching});

// OpenRouterconst llm = new OpenAILLMAdapter({  apiKey: process.env.OPENROUTER_API_KEY!,  baseURL: "https://openrouter.ai/api/v1",  defaultModel: "openai/gpt-4o-mini",});
// Together AIconst llm = new OpenAILLMAdapter({  apiKey: process.env.TOGETHER_API_KEY!,  baseURL: "https://api.together.xyz/v1",  defaultModel: "meta-llama/Llama-3.3-70B-Instruct-Turbo",});
// Gemini (OpenAI-compatible endpoint)const llm = new OpenAILLMAdapter({  apiKey: process.env.GEMINI_API_KEY!,  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai",  defaultModel: "gemini-2.0-flash",});

// 1. Store what happenedawait memstack.memory.store({  actorId: "support-bot-42",  content: "User reports login failing with error 503 on Chrome 125.",  tags: ["login", "bug", "chrome"],  importance: 0.8,});
// 2. Later, retrieve relevant contextconst memories = await memstack.memory.retrieve({  actorId: "support-bot-42",  query: "login error",  strategy: "hybrid",});
// 3. Assemble an LLM-ready contextconst ctx = await memstack.memory.compileContext({  actorId: "support-bot-42",  maxTokens: 2000,});
const response = await llm.complete({  system: `You are a support bot. Here is what you remember:\n${ctx.systemPrompt}`,  user: "The user is back and still can't log in. What do you do?",});
console.log(response.text);// "Based on our history, the user has been experiencing 503 errors on Chrome 125..."
// 4. Every 100 interactions, summarization triggers automatically.// Old interactions are compressed into a paragraph. Token costs stay flat.

interface Memory {  id: string;  actorId: string;               // Who this memory belongs to (user ID, agent ID, session ID)  memoryType: MemoryType;        // "interaction" | "summary" | "observation" | "fact" | "reflection" | "preference" | "decision" | "instruction"  content: string;               // The actual text  importance: number;            // 0-1 — higher = survives pruning, ranks higher in retrieval  emotionalValence: number;      // -1 to 1 — for tone-aware retrieval  tags: string[];                // Filter by tag: "bug", "billing", "urgent", etc.  embedding?: number[];          // Computed automatically if embedding adapter is configured  metadata?: Record<string, unknown>;  // Your custom fields  expiresAt?: Date;              // Auto-pruned after this date  sourceId?: string;             // Link back to the originating event  createdAt: Date;}

// Simple storeawait ms.memory.store({  actorId: "agent-7",  content: "Customer asked about refund policy for Q2 purchases.",  tags: ["billing", "refund"],});
// Batch store — embeddings are batched into one API call for efficiencyawait ms.memory.storeBatch([  { actorId: "agent-7", content: "First interaction" },  { actorId: "agent-7", content: "Second interaction" },  { actorId: "agent-7", content: "Third interaction" },]);

const memories = await ms.memory.retrieve({  actorId: "agent-7",              // Scope to one actor  query: "refund policy",          // What to search for  strategy: "hybrid",              // How to rank: "recent" | "important" | "semantic" | "hybrid"  limit: 10,                       // Max results  memoryTypes: ["interaction"],    // Only certain types  tags: ["billing"],               // Only certain tags});

const ctx = await ms.memory.compileContext({  actorId: "agent-7",  maxTokens: 2000,               // Budget — assembler stops when it hits this  memoryTypes: ["interaction", "summary"],});
// ctx.systemPrompt:// ## Important Memories// - The customer has been attempting login for 3 days. (importance: 0.85)// - Refund was processed for order #4521 on Jan 12. (importance: 0.72)// // ## Recent Interactions// - Customer asked about refund policy for Q2 purchases.// - Customer reported login error 503 on Chrome 125.
console.log(ctx.tokenEstimate);  // ~280
// Inject into your LLM callconst currentMessage = "The user is asking about their refund status.";const response = await llm.complete({  system: ctx.systemPrompt,  user: currentMessage,});
console.log(response.text);

const { summary, deletedCount } = await ms.memory.summarize({  actorId: "agent-7",  olderThan: new Date(Date.now() - 7 * 86400000),  // Older than 7 days  skipMostRecent: 10,        // Never touch the 10 most recent  targetCount: 50,           // Summarize at most 50 memories  memoryTypes: ["interaction"],  keepOriginals: false,      // Delete originals after summary});
// summary.content:// "Over the past week, the customer reported recurring login failures (error 503)//  on Chrome 125. Multiple troubleshooting attempts including cache clearing and //  password reset were unsuccessful. A refund was processed for order #4521."
console.log(deletedCount);   // 47 — 47 interactions compressed into 1 summary memory

const ms = new MemStack({  llm,  defaults: {    summarizationPrompt:      "You are an enterprise support memory compressor. Highlight: customer name,       product, severity, resolution status, and any open issues.",  },});

// Remove memories older than 30 daysawait ms.memory.prune({ type: "byAge", maxAge: 30 * 86400000 });
// Keep only memories above importance 0.3await ms.memory.prune({ type: "byImportance", minImportance: 0.3 });
// Keep at most 500 memories per actorawait ms.memory.prune({ type: "byCount", maxPerActor: 500 });
// Remove specific typesawait ms.memory.prune({ type: "byType", memoryTypes: ["observation"] });
// Custom logicawait ms.memory.prune({  type: "custom",  shouldRemove: (memory) => memory.content.includes("[RESOLVED]"),});
// Dry run first — see what would be removedconst { wouldPrune, count } = await ms.memory.dryRunPrune({  type: "byAge",  maxAge: 86400000,});console.log(`Would remove ${count} memories:`, wouldPrune);

const ms = new MemStack({  llm,  defaults: {    pruneStrategy: { type: "byImportance", minImportance: 0.05 },  },});

// detectUrgency and classifyIntent are your own business logic.// They could be simple keyword matchers, regex, or an LLM call.function detectUrgency(msg: string): number {  if (msg.match(/urgent|asap|immediately/i)) return 0.9;  if (msg.match(/error|fail|broken/i)) return 0.7;  return 0.5;}
function classifyIntent(msg: string): string[] {  const tags: string[] = [];  if (msg.match(/bill|refund|charge|payment/i)) tags.push("billing");  if (msg.match(/error|bug|fail|crash/i)) tags.push("bug");  if (msg.match(/login|password|account/i)) tags.push("account");  return tags;}
// Every customer message becomes a memoryasync function handleMessage(customerId: string, message: string) {  await ms.memory.store({    actorId: `customer:${customerId}`,    content: message,    importance: detectUrgency(message),    tags: classifyIntent(message),  });
  // Retrieve everything relevant to this customer's history  const ctx = await ms.memory.compileContext({    actorId: `customer:${customerId}`,    maxTokens: 1500,  });
  const response = await llm.complete({    system: `You are a support agent. Customer history:\n${ctx.systemPrompt}`,    user: message,  });
  return response.text;}
// Every 100th interaction, old history auto-compresses.// A customer with 10,000 messages still fits in a $0.02 LLM call.

// Suppose you have documents from your knowledge baseconst documents = [  { text: "Authentication uses JWT tokens with 15-minute expiry.", url: "/docs/auth", section: "security" },  { text: "Refunds are processed within 5-10 business days.", url: "/docs/billing", section: "billing" },];
// Index documents as observation memoriesfor (const doc of documents) {  await ms.memory.store({    actorId: "knowledge-base",    content: doc.text,    memoryType: "observation",    metadata: { source: doc.url, section: doc.section },  });}
// Query with semantic searchconst relevantDocs = await ms.memory.retrieve({  actorId: "knowledge-base",  query: "How does authentication work?",  strategy: "semantic",  limit: 5,});
const ctx = await ms.memory.compileContext({  actorId: "knowledge-base",  memoryTypes: ["observation"],});
// Prompt the LLM with retrieved contextconst answer = await llm.complete({  system: `Answer using only these documents:\n${ctx.systemPrompt}`,  user: "How does authentication work?",});

// Each user gets their own memory spaceasync function chat(userId: string, message: string) {  await ms.memory.store({    actorId: userId,    content: message,  });
  const ctx = await ms.memory.compileContext({    actorId: userId,    maxTokens: 1000,  });
  return llm.complete({    system: `You are a friendly assistant. Conversation history with this user:\n${ctx.systemPrompt}`,    user: message,  });}
// Get statsconst total = await ms.memory.count();const userCount = await ms.memory.count({ actorId: "user-42" });

// "What just happened?" — most recent firstawait ms.memory.retrieve({ actorId: "x", strategy: "recent", limit: 3 });
// "What matters most?" — highest importance, ignoring ageawait ms.memory.retrieve({ actorId: "x", strategy: "important" });
// "What relates to this query?" — cosine similarity search (needs embeddings)await ms.memory.retrieve({ actorId: "x", query: "login bug", strategy: "semantic" });
// "Balance relevance and importance" — semantic + importance blendawait ms.memory.retrieve({ actorId: "x", query: "login bug", strategy: "hybrid" });

import { LexicalRetriever } from "@memstack/core";
const retriever = new LexicalRetriever(storage);const { hits, fallback } = await retriever.recall({  actorIds: ["project:abc", "global"], // Searched together  query: "What framework does this project use?",  limit: 10,                           // Max results  maxChars: 8000,                      // Max total content; the top hit is always returned});

import { MemStack, OpenAILLMAdapter, OpenAIEmbeddingAdapter, InMemoryStorageAdapter } from "@memstack/core";
const ms = new MemStack({  llm: new OpenAILLMAdapter({ apiKey: process.env.OPENAI_API_KEY! }),  embedding: new OpenAIEmbeddingAdapter({ apiKey: process.env.OPENAI_API_KEY! }),  storage: new InMemoryStorageAdapter(),});
// store() computes a 1536-dim vector automaticallyawait ms.memory.store({  actorId: "agent-7",  content: "Customer asked about refund policy for Q2 purchases.",});
// retrieve() with "semantic" or "hybrid" uses cosine similarity// Query: "refund" finds the refund policy memory even though the word "refund"// appears differently across stored memories.const results = await ms.memory.retrieve({  actorId: "agent-7",  query: "how do I get my money back",  strategy: "semantic",});// Matches "Customer asked about refund policy" — semantic match, not keyword match.

const ms = new MemStack({  llm: new OpenAILLMAdapter({ apiKey: process.env.OPENAI_API_KEY! }),  storage: new InMemoryStorageAdapter(),  // no embedding adapter});
// store() works identically, just no vector computedawait ms.memory.store({  actorId: "agent-7",  content: "Customer asked about refund policy for Q2 purchases.",});
// retrieve() with "semantic" or "hybrid" falls back to keyword matching// plus importance/recency sorting. No API costs, no setup required.const results = await ms.memory.retrieve({  actorId: "agent-7",  query: "refund",  strategy: "hybrid", // falls back to keyword + importance});// Still works — finds "refund" via substring match. Less precise for// paraphrased queries ("money back" won't match "refund").

// Disable auto-embedding if you only need keyword searchconst ms = new MemStack({  llm,  embedding: new OpenAIEmbeddingAdapter({ apiKey }),  defaults: { embedOnStore: false },});

// OpenAIimport { OpenAILLMAdapter } from "@memstack/core";const llm = new OpenAILLMAdapter({ apiKey: "..." });
// Any OpenAI-compatible API — just change baseURLconst deepseek = new OpenAILLMAdapter({ apiKey: "...", baseURL: "https://api.deepseek.com/v1" });const mistral = new OpenAILLMAdapter({ apiKey: "...", baseURL: "https://api.mistral.ai/v1" });const together = new OpenAILLMAdapter({ apiKey: "...", baseURL: "https://api.together.xyz/v1" });
// Anthropicimport { AnthropicLLMAdapter } from "@memstack/core";const llm = new AnthropicLLMAdapter({  apiKey: process.env.ANTHROPIC_API_KEY!,  defaultModel: "claude-sonnet-4-5-20250929",});
// Ollama (built-in)import { OllamaLLMAdapter } from "@memstack/core";const llm = new OllamaLLMAdapter({  baseURL: "http://localhost:11434",  defaultModel: "llama3.2",});

import { OpenAIEmbeddingAdapter, CohereEmbeddingAdapter } from "@memstack/core";
// OpenAInew OpenAIEmbeddingAdapter({ apiKey: "...", model: "text-embedding-3-small" }); // 1536 dims
// Coherenew CohereEmbeddingAdapter({ apiKey: "..." }); // embed-english-v3.0, 1024 dims
// Any OpenAI-compatible embedding APInew OpenAIEmbeddingAdapter({ apiKey: "...", baseURL: "https://api.voyageai.com/v1", model: "voyage-3" });

import { MemStack } from "@memstack/core";
const ms = new MemStack({  llm: LLMProvider,                    // Required — for summarization  embedding?: EmbeddingProvider,       // Optional — for semantic search  storage?: StorageProvider,           // Optional — defaults to InMemoryStorageAdapter  defaults?: {    summarizationThreshold?: number,   // Auto-summarize every N process() calls. Default: 100    embedOnStore?: boolean,            // Auto-embed on store(). Default: true    pruneStrategy?: PruneStrategy,     // Auto-prune during process() (throttled). Default: disabled    pruneInterval?: number,            // Run auto-prune every N process() calls. Default: 100    autoImportance?: boolean,          // LLM-score importance in process() when not provided. Default: false    autoTags?: boolean,                // LLM-extract tags in process() when not provided. Default: false    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;  },});

// Storems.memory.store(input: MemoryStoreInput): Promise<Memory>ms.memory.storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]>
// Retrievems.memory.retrieve(query: MemoryRetrieveQuery): Promise<Memory[]>ms.memory.get(id: string): Promise<Memory | null>
// Context assemblyms.memory.compileContext(options: ContextOptions): Promise<CompiledContext>
// Lifecyclems.memory.summarize(options: SummarizeOptions): Promise<{ summary: Memory; deletedCount: number }>ms.memory.prune(strategy: PruneStrategy): Promise<{ pruned: string[]; count: number }>ms.memory.dryRunPrune(strategy: PruneStrategy): Promise<{ wouldPrune: string[]; count: number }>
// Managementms.memory.count(filter?: MemoryCountFilter): Promise<number>ms.memory.delete(id: string): Promise<void>ms.memory.deleteMany(ids: string[]): Promise<number>ms.memory.touch(id: string): Promise<void>ms.memory.purgeActor(actorId: string): Promise<number>ms.memory.merge(ids: string[]): Promise<Memory>ms.memory.stats(actorId?: string): Promise<MemoryStats>ms.memory.summarizeStream(options: SummarizeOptions): AsyncIterable<{ chunk: string; text: string }>

import * as fs from "node:fs";
// Saveconst snapshot = await ms.export();fs.writeFileSync("state.json", JSON.stringify(snapshot, null, 2));
// Restoreconst data = JSON.parse(fs.readFileSync("state.json", "utf-8"));await ms2.import(data);

const status = await ms.health();// { storage: true, llm: true, embedding: true }
await ms.close(); // graceful shutdown

import { HarnessMemory, defaultRecallNamespaces, projectNamespace } from "@memstack/core";
const memory = new HarnessMemory({ storage, llm });
await memory.remember({  namespace: projectNamespace("acme-api"),   // or "global"  content: "This project uses Hono",  kind: "decision",                           // fact | preference | decision | instruction | observation | ...  source: { harness: "my-agent", project: "acme-api" },});
const { hits, fallback } = await memory.recall({  namespaces: defaultRecallNamespaces("acme-api"), // project, then global  query: "Which framework do we use?",  limit: 10,  maxChars: 8000,});
await memory.get(id, namespaces);       // null outside namespacesawait memory.forget(id, namespaces);    // refuses ids outside namespacesawait memory.stats(namespaces);         // { "project:acme-api": 3, global: 1 }await memory.moveNamespace(from, to);   // e.g. when a project's ID changes

const ms = new MemStack({  llm: new OpenAILLMAdapter({ apiKey: "..." }),
  // Defaults control auto-behavior (all applied during process())  defaults: {    summarizationThreshold: 50,      // Summarize every 50 process() calls (default: 100)    embedOnStore: false,             // Don't auto-embed — saves API costs    pruneStrategy: {                 // Auto-clean during process(), throttled by pruneInterval      type: "byAge",      maxAge: 90 * 86400000,         // 90 days    },    pruneInterval: 100,              // Run the prune check every 100 process() calls (default: 100)    autoImportance: true,            // Let the LLM score importance when you don't pass one    autoTags: true,                  // Let the LLM extract tags when you don't pass any  },
  // Hooks for observability  hooks: {    onMemoryStored: (m) => logger.debug("memory:stored", { id: m.id, actor: m.actorId }),    onMemoryPruned: (ids) => logger.info("memory:pruned", { count: ids.length }),    onSummaryCreated: (summary, n) => logger.info("memory:summarized", { count: n }),    onError: (err, context) => logger.error("memory:error", { context, message: err.message }),  },});

import type { LLMProvider } from "@memstack/core";
class TogetherAIAdapter implements LLMProvider {  async complete(req: { system: string; user: string; model?: string }) {    const res = await fetch("https://api.together.xyz/v1/chat/completions", {      headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },      body: JSON.stringify({ model: req.model, messages: [{ role: "system", content: req.system }, { role: "user", content: req.user }] }),    });    const data = await res.json() as any;    return { text: data.choices[0].message.content, tokens: { prompt: data.usage.prompt_tokens, completion: data.usage.completion_tokens, total: data.usage.total_tokens } };  }}

const ms = new MemStack({  llm,  hooks: {    onMemoryStored: (m) => metrics.increment("memory.stored"),    onSummaryCreated: (_, n) => metrics.gauge("memory.summarized_count", n),    onMemoryPruned: (ids) => metrics.increment("memory.pruned", ids.length),  },});

const ms = new MemStack({  llm,  hooks: {    onMemoryStored: (m) => console.debug("[memstack] stored:", m.id, m.content.slice(0, 80)),    onMemoryPruned: (ids) => console.debug("[memstack] pruned:", ids.length),  },});

// How much data do we have?const total = await ms.memory.count();const perActor = await ms.memory.count({ actorId: "user-42" });
// What does one actor's memory look like?const snapshot = await ms.export();const actorMemories = snapshot.memories.filter(m => m.actorId === "user-42");console.log(`User-42: ${actorMemories.length} memories`);actorMemories.forEach(m => console.log(`  [${m.memoryType}] ${m.content.slice(0, 60)} (imp: ${m.importance})`));