@clawpify/skills 1.0.7 → 1.0.9

package/dist/agent.d.ts

@@ -46,13 +46,25 @@ export interface ThinkingConfig {
     /** Token budget for thinking. Must be >= 1024. */
     budgetTokens: number;
 }
+/** Structured context for prompt assembly. Used when systemInstruction is not provided. */
+export interface AgentContextConfig {
+    /** Heartbeat content (only for new sessions). Injected at prompt start. */
+    heartbeatContent?: string;
+    /** Long-term memory content. Always included. */
+    memoryContent?: string;
+    /** Base system instruction override. Falls back to DEFAULT_SYSTEM_INSTRUCTION. */
+    baseInstruction?: string;
+}
 /** Full configuration accepted by the ShopifyAgent constructor. */
 export interface AgentConfig {
     shopify: ShopifyClient;
     skillContent: string;
     model?: string;
-    /** Override the default system instruction sent to the model. */
+    /** Override the default system instruction sent to the model (raw string). */
     systemInstruction?: string;
+    /** Structured context assembled into a system instruction internally.
+     *  Ignored when systemInstruction is provided. */
+    context?: AgentContextConfig;
     /** Override default Claude Sonnet pricing. */
     pricing?: ModelPricing;
     /** Register plugins at construction time. */

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -48,6 +48,19 @@ async function collectMarkdown(dir, parts) {
 
 // src/agent.ts
 import Anthropic from "@anthropic-ai/sdk";
+
+// src/prompt-utils.ts
+var MAX_HEARTBEAT_CHARS = 2000;
+var MAX_MEMORY_CHARS = 4000;
+function clampContent(content, maxChars) {
+  const trimmed = content.trim();
+  if (trimmed.length <= maxChars)
+    return trimmed;
+  return trimmed.slice(0, maxChars).trimEnd() + `
+...[truncated]`;
+}
+
+// src/agent.ts
 var DEFAULT_SYSTEM_INSTRUCTION = "You're Clawpify. You help run a Shopify store. The merchant texts you to get stuff done";
 var SHOPIFY_GRAPHQL_TOOL = {
   name: "shopify_graphql",
@@ -128,6 +141,29 @@ function extractContent(response) {
   }
   return { text, thinking };
 }
+function buildSystemInstruction(ctx) {
+  const base = ctx.baseInstruction ?? DEFAULT_SYSTEM_INSTRUCTION;
+  let heartbeatBlock = "";
+  if (ctx.heartbeatContent?.trim()) {
+    heartbeatBlock = `
+
+This is a NEW conversation (no recent chat history). ` + "Follow these instructions first, then respond to the merchant's message. " + `Keep the summary brief (1-2 sentences), then address what they asked.
+
+---
+` + clampContent(ctx.heartbeatContent, MAX_HEARTBEAT_CHARS) + `
+---`;
+  }
+  let memoryBlock = "";
+  if (ctx.memoryContent?.trim()) {
+    memoryBlock = `
+
+Things to remember about this merchant/store ` + `(use this context in your responses):
+---
+` + clampContent(ctx.memoryContent, MAX_MEMORY_CHARS) + `
+---`;
+  }
+  return base + heartbeatBlock + memoryBlock;
+}
 
 class ShopifyAgent {
   anthropic;
@@ -145,7 +181,13 @@ class ShopifyAgent {
     this.anthropic = new Anthropic;
     this.shopify = config.shopify;
     this.skillContent = config.skillContent;
-    this.systemInstruction = config.systemInstruction ?? DEFAULT_SYSTEM_INSTRUCTION;
+    if (config.systemInstruction != null) {
+      this.systemInstruction = config.systemInstruction;
+    } else if (config.context) {
+      this.systemInstruction = buildSystemInstruction(config.context);
+    } else {
+      this.systemInstruction = DEFAULT_SYSTEM_INSTRUCTION;
+    }
     this.model = config.model ?? "claude-sonnet-4-5";
     this.pricing = config.pricing ?? DEFAULT_PRICING;
     this.hooks = config.hooks ?? {};

package/dist/index.d.ts

@@ -36,9 +36,10 @@
 export { ShopifyClient, createShopifyClient } from "./shopify";
 export { createAuthenticatedConfig, getAccessToken, type AccessTokenResponse, type ClientCredentialsConfig, } from "./auth";
 export { ShopifyAgent, DEFAULT_SYSTEM_INSTRUCTION } from "./agent";
-export type { AgentConfig, AgentHooks, AgentPlugin, ChatResult, ModelPricing, StreamEvent, ThinkingConfig, TokenUsage, } from "./agent";
+export type { AgentConfig, AgentContextConfig, AgentHooks, AgentPlugin, ChatResult, ModelPricing, StreamEvent, ThinkingConfig, TokenUsage, } from "./agent";
 export { InMemoryStore } from "./memory";
-export type { MemoryStore } from "./memory";
+export type { MemoryStore, LoadResult } from "./memory";
+export { clampContent, MAX_HEARTBEAT_CHARS, MAX_MEMORY_CHARS } from "./prompt-utils";
 export { loadSkills, loadSkillMetadata, loadSkillReference, listSkillReferences, } from "./skills";
 export type { ShopifyClientConfig, GraphQLResponse } from "./shopify";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAG/D,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AACnE,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAGlB,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAG/D,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AACnE,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGrF,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAGlB,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -137,6 +137,19 @@ async function collectMarkdown(dir, parts) {
 
 // src/agent.ts
 import Anthropic from "@anthropic-ai/sdk";
+
+// src/prompt-utils.ts
+var MAX_HEARTBEAT_CHARS = 2000;
+var MAX_MEMORY_CHARS = 4000;
+function clampContent(content, maxChars) {
+  const trimmed = content.trim();
+  if (trimmed.length <= maxChars)
+    return trimmed;
+  return trimmed.slice(0, maxChars).trimEnd() + `
+...[truncated]`;
+}
+
+// src/agent.ts
 var DEFAULT_SYSTEM_INSTRUCTION = "You're Clawpify. You help run a Shopify store. The merchant texts you to get stuff done";
 var SHOPIFY_GRAPHQL_TOOL = {
   name: "shopify_graphql",
@@ -217,6 +230,29 @@ function extractContent(response) {
   }
   return { text, thinking };
 }
+function buildSystemInstruction(ctx) {
+  const base = ctx.baseInstruction ?? DEFAULT_SYSTEM_INSTRUCTION;
+  let heartbeatBlock = "";
+  if (ctx.heartbeatContent?.trim()) {
+    heartbeatBlock = `
+
+This is a NEW conversation (no recent chat history). ` + "Follow these instructions first, then respond to the merchant's message. " + `Keep the summary brief (1-2 sentences), then address what they asked.
+
+---
+` + clampContent(ctx.heartbeatContent, MAX_HEARTBEAT_CHARS) + `
+---`;
+  }
+  let memoryBlock = "";
+  if (ctx.memoryContent?.trim()) {
+    memoryBlock = `
+
+Things to remember about this merchant/store ` + `(use this context in your responses):
+---
+` + clampContent(ctx.memoryContent, MAX_MEMORY_CHARS) + `
+---`;
+  }
+  return base + heartbeatBlock + memoryBlock;
+}
 
 class ShopifyAgent {
   anthropic;
@@ -234,7 +270,13 @@ class ShopifyAgent {
     this.anthropic = new Anthropic;
     this.shopify = config.shopify;
     this.skillContent = config.skillContent;
-    this.systemInstruction = config.systemInstruction ?? DEFAULT_SYSTEM_INSTRUCTION;
+    if (config.systemInstruction != null) {
+      this.systemInstruction = config.systemInstruction;
+    } else if (config.context) {
+      this.systemInstruction = buildSystemInstruction(config.context);
+    } else {
+      this.systemInstruction = DEFAULT_SYSTEM_INSTRUCTION;
+    }
     this.model = config.model ?? "claude-sonnet-4-5";
     this.pricing = config.pricing ?? DEFAULT_PRICING;
     this.hooks = config.hooks ?? {};
@@ -561,6 +603,9 @@ class InMemoryStore {
   async clear(sessionId) {
     this.store.delete(sessionId);
   }
+  async loadWithStatus(sessionId) {
+    return { history: await this.load(sessionId), error: false };
+  }
 }
 export {
   loadSkills,
@@ -570,8 +615,11 @@ export {
   getAccessToken,
   createShopifyClient,
   createAuthenticatedConfig,
+  clampContent,
   ShopifyClient,
   ShopifyAgent,
+  MAX_MEMORY_CHARS,
+  MAX_HEARTBEAT_CHARS,
   InMemoryStore,
   DEFAULT_SYSTEM_INSTRUCTION
 };

package/dist/memory.d.ts

@@ -1,3 +1,8 @@
+/** Result of loadWithStatus() — distinguishes empty history from a storage error. */
+export interface LoadResult {
+    history: any[];
+    error: boolean;
+}
 /**
  * Interface for persisting conversation history across sessions.
  * Implement this interface to plug in any storage backend (Redis, SQLite, etc.).
@@ -12,6 +17,8 @@ export interface MemoryStore {
     load(sessionId: string): Promise<any[]>;
     /** Clear conversation history for a session. */
     clear(sessionId: string): Promise<void>;
+    /** Optional: load with error status for callers that need to distinguish empty from failed. */
+    loadWithStatus?(sessionId: string): Promise<LoadResult>;
 }
 /**
  * Simple in-memory implementation of MemoryStore.
@@ -22,5 +29,6 @@ export declare class InMemoryStore implements MemoryStore {
     save(sessionId: string, history: any[]): Promise<void>;
     load(sessionId: string): Promise<any[]>;
     clear(sessionId: string): Promise<void>;
+    loadWithStatus(sessionId: string): Promise<LoadResult>;
 }
 //# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD,iFAAiF;IACjF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAExC,gDAAgD;IAChD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,KAAK,CAA4B;IAEnC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAKvC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,GAAG,EAAE,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD,iFAAiF;IACjF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAExC,gDAAgD;IAChD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC,+FAA+F;IAC/F,cAAc,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACzD;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,KAAK,CAA4B;IAEnC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAKvC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAG7D"}

package/dist/memory.js

@@ -11,6 +11,9 @@ class InMemoryStore {
   async clear(sessionId) {
     this.store.delete(sessionId);
   }
+  async loadWithStatus(sessionId) {
+    return { history: await this.load(sessionId), error: false };
+  }
 }
 export {
   InMemoryStore

package/dist/prompt-utils.d.ts

@@ -0,0 +1,7 @@
+/** Max characters allowed for heartbeat content to prevent context bloat. */
+export declare const MAX_HEARTBEAT_CHARS = 2000;
+/** Max characters allowed for memory content to prevent context bloat. */
+export declare const MAX_MEMORY_CHARS = 4000;
+/** Clamp content to a max character count, appending a truncation marker. */
+export declare function clampContent(content: string, maxChars: number): string;
+//# sourceMappingURL=prompt-utils.d.ts.map

package/dist/prompt-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-utils.d.ts","sourceRoot":"","sources":["../src/prompt-utils.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAItE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawpify/skills",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Shopify Agent SDK — query and manage Shopify stores via GraphQL Admin API with AI agents and MCP",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,9 +68,6 @@
     "model-context-protocol"
   ],
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/clawpify/skills.git"

package/src/agent.test.ts

@@ -1,9 +1,10 @@
 import { describe, test, expect, mock } from "bun:test";
 import { ShopifyAgent, DEFAULT_SYSTEM_INSTRUCTION } from "./agent";
-import type { AgentPlugin, AgentHooks, ModelPricing } from "./agent";
+import type { AgentPlugin, AgentHooks, AgentContextConfig, ModelPricing } from "./agent";
 import { ShopifyClient } from "./shopify";
 import { InMemoryStore } from "./memory";
 import type { MemoryStore } from "./memory";
+import { clampContent, MAX_HEARTBEAT_CHARS, MAX_MEMORY_CHARS } from "./prompt-utils";
 
 // ---------------------------------------------------------------------------
 // Helpers — build realistic Anthropic response shapes
@@ -107,6 +108,7 @@ function createAgent(
     hooks?: AgentHooks;
     pricing?: ModelPricing;
     systemInstruction?: string;
+    context?: AgentContextConfig;
     thinking?: { budgetTokens: number };
     maxIterations?: number;
     memory?: MemoryStore;
@@ -924,4 +926,133 @@ describe("InMemoryStore", () => {
     const loaded = await store.load("test");
     expect(loaded[0].content).toBe("Original");
   });
+
+  test("loadWithStatus returns history and error: false", async () => {
+    const store = new InMemoryStore();
+    const history = [
+      { role: "user", content: "Hello" },
+      { role: "assistant", content: "Hi!" },
+    ];
+
+    await store.save("test", history);
+    const result = await store.loadWithStatus("test");
+
+    expect(result.error).toBe(false);
+    expect(result.history).toEqual(history);
+  });
+
+  test("loadWithStatus returns empty history for unknown session", async () => {
+    const store = new InMemoryStore();
+    const result = await store.loadWithStatus("nonexistent");
+
+    expect(result).toEqual({ history: [], error: false });
+  });
+});
+
+// ==========================================================================
+// 11. clampContent & prompt constants
+// ==========================================================================
+
+describe("clampContent", () => {
+  test("returns trimmed content when under limit", () => {
+    expect(clampContent("  hello world  ", 100)).toBe("hello world");
+  });
+
+  test("truncates content that exceeds maxChars", () => {
+    const long = "a".repeat(3000);
+    const result = clampContent(long, 2000);
+    expect(result).toContain("...[truncated]");
+    // The content portion should be at most maxChars
+    expect(result.replace("\n...[truncated]", "").length).toBeLessThanOrEqual(
+      2000
+    );
+  });
+
+  test("returns exact content at the boundary", () => {
+    const exact = "b".repeat(2000);
+    expect(clampContent(exact, 2000)).toBe(exact);
+  });
+
+  test("constants have expected values", () => {
+    expect(MAX_HEARTBEAT_CHARS).toBe(2000);
+    expect(MAX_MEMORY_CHARS).toBe(4000);
+  });
+});
+
+// ==========================================================================
+// 12. AgentContextConfig
+// ==========================================================================
+
+describe("AgentContextConfig", () => {
+  test("systemInstruction as string still works (backward compat)", () => {
+    const agent = createAgent({
+      systemInstruction: "Custom instruction",
+    });
+
+    const instruction = (agent as any).systemInstruction;
+    expect(instruction).toBe("Custom instruction");
+  });
+
+  test("uses DEFAULT_SYSTEM_INSTRUCTION when neither systemInstruction nor context provided", () => {
+    const agent = createAgent();
+
+    const instruction = (agent as any).systemInstruction;
+    expect(instruction).toBe(DEFAULT_SYSTEM_INSTRUCTION);
+  });
+
+  test("assembles prompt from context when systemInstruction is not provided", () => {
+    const agent = createAgent({
+      context: {
+        heartbeatContent: "Check sales report",
+        memoryContent: "This store sells sneakers",
+      },
+    });
+
+    const instruction: string = (agent as any).systemInstruction;
+
+    // Should start with the default base
+    expect(instruction).toContain(DEFAULT_SYSTEM_INSTRUCTION);
+    // Should include heartbeat block
+    expect(instruction).toContain("NEW conversation");
+    expect(instruction).toContain("Check sales report");
+    // Should include memory block
+    expect(instruction).toContain("Things to remember");
+    expect(instruction).toContain("This store sells sneakers");
+  });
+
+  test("systemInstruction takes precedence over context", () => {
+    const agent = createAgent({
+      systemInstruction: "Override wins",
+      context: {
+        heartbeatContent: "Should not appear",
+        memoryContent: "Should not appear either",
+      },
+    });
+
+    const instruction: string = (agent as any).systemInstruction;
+    expect(instruction).toBe("Override wins");
+  });
+
+  test("context with baseInstruction overrides the default", () => {
+    const agent = createAgent({
+      context: {
+        baseInstruction: "You are a custom assistant.",
+        memoryContent: "Sells hats",
+      },
+    });
+
+    const instruction: string = (agent as any).systemInstruction;
+    expect(instruction).toContain("You are a custom assistant.");
+    expect(instruction).toContain("Sells hats");
+    expect(instruction).not.toContain(DEFAULT_SYSTEM_INSTRUCTION);
+  });
+
+  test("context with no dynamic content uses base instruction only", () => {
+    const agent = createAgent({
+      context: {},
+    });
+
+    const instruction: string = (agent as any).systemInstruction;
+    expect(instruction).toBe(DEFAULT_SYSTEM_INSTRUCTION);
+  });
 });

package/src/agent.ts

@@ -2,6 +2,11 @@ import Anthropic from "@anthropic-ai/sdk";
 import { ShopifyClient } from "./shopify";
 import type { MemoryStore } from "./memory";
 import { loadSkillReference } from "./skills";
+import {
+  clampContent,
+  MAX_HEARTBEAT_CHARS,
+  MAX_MEMORY_CHARS,
+} from "./prompt-utils";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -75,13 +80,26 @@ export interface ThinkingConfig {
   budgetTokens: number;
 }
 
+/** Structured context for prompt assembly. Used when systemInstruction is not provided. */
+export interface AgentContextConfig {
+  /** Heartbeat content (only for new sessions). Injected at prompt start. */
+  heartbeatContent?: string;
+  /** Long-term memory content. Always included. */
+  memoryContent?: string;
+  /** Base system instruction override. Falls back to DEFAULT_SYSTEM_INSTRUCTION. */
+  baseInstruction?: string;
+}
+
 /** Full configuration accepted by the ShopifyAgent constructor. */
 export interface AgentConfig {
   shopify: ShopifyClient;
   skillContent: string;
   model?: string;
-  /** Override the default system instruction sent to the model. */
+  /** Override the default system instruction sent to the model (raw string). */
   systemInstruction?: string;
+  /** Structured context assembled into a system instruction internally.
+   *  Ignored when systemInstruction is provided. */
+  context?: AgentContextConfig;
   /** Override default Claude Sonnet pricing. */
   pricing?: ModelPricing;
   /** Register plugins at construction time. */
@@ -243,6 +261,32 @@ function extractContent(response: Anthropic.Message): {
   return { text, thinking };
 }
 
+/** Assemble a system instruction from structured AgentContextConfig. */
+function buildSystemInstruction(ctx: AgentContextConfig): string {
+  const base = ctx.baseInstruction ?? DEFAULT_SYSTEM_INSTRUCTION;
+
+  let heartbeatBlock = "";
+  if (ctx.heartbeatContent?.trim()) {
+    heartbeatBlock =
+      "\n\nThis is a NEW conversation (no recent chat history). " +
+      "Follow these instructions first, then respond to the merchant's message. " +
+      "Keep the summary brief (1-2 sentences), then address what they asked.\n\n---\n" +
+      clampContent(ctx.heartbeatContent, MAX_HEARTBEAT_CHARS) +
+      "\n---";
+  }
+
+  let memoryBlock = "";
+  if (ctx.memoryContent?.trim()) {
+    memoryBlock =
+      "\n\nThings to remember about this merchant/store " +
+      "(use this context in your responses):\n---\n" +
+      clampContent(ctx.memoryContent, MAX_MEMORY_CHARS) +
+      "\n---";
+  }
+
+  return base + heartbeatBlock + memoryBlock;
+}
+
 // ---------------------------------------------------------------------------
 // Agent
 // ---------------------------------------------------------------------------
@@ -264,8 +308,15 @@ export class ShopifyAgent {
     this.anthropic = new Anthropic();
     this.shopify = config.shopify;
     this.skillContent = config.skillContent;
-    this.systemInstruction =
-      config.systemInstruction ?? DEFAULT_SYSTEM_INSTRUCTION;
+
+    if (config.systemInstruction != null) {
+      this.systemInstruction = config.systemInstruction;
+    } else if (config.context) {
+      this.systemInstruction = buildSystemInstruction(config.context);
+    } else {
+      this.systemInstruction = DEFAULT_SYSTEM_INSTRUCTION;
+    }
+
     this.model = config.model ?? "claude-sonnet-4-5";
     this.pricing = config.pricing ?? DEFAULT_PRICING;
     this.hooks = config.hooks ?? {};

package/src/index.ts

@@ -49,6 +49,7 @@ export {
 export { ShopifyAgent, DEFAULT_SYSTEM_INSTRUCTION } from "./agent";
 export type {
   AgentConfig,
+  AgentContextConfig,
   AgentHooks,
   AgentPlugin,
   ChatResult,
@@ -60,7 +61,10 @@ export type {
 
 // Memory
 export { InMemoryStore } from "./memory";
-export type { MemoryStore } from "./memory";
+export type { MemoryStore, LoadResult } from "./memory";
+
+// Prompt utilities
+export { clampContent, MAX_HEARTBEAT_CHARS, MAX_MEMORY_CHARS } from "./prompt-utils";
 
 // Skills loader
 export {

package/src/memory.ts

@@ -1,3 +1,9 @@
+/** Result of loadWithStatus() — distinguishes empty history from a storage error. */
+export interface LoadResult {
+  history: any[];
+  error: boolean;
+}
+
 /**
  * Interface for persisting conversation history across sessions.
  * Implement this interface to plug in any storage backend (Redis, SQLite, etc.).
@@ -14,6 +20,9 @@ export interface MemoryStore {
 
   /** Clear conversation history for a session. */
   clear(sessionId: string): Promise<void>;
+
+  /** Optional: load with error status for callers that need to distinguish empty from failed. */
+  loadWithStatus?(sessionId: string): Promise<LoadResult>;
 }
 
 /**
@@ -35,4 +44,8 @@ export class InMemoryStore implements MemoryStore {
   async clear(sessionId: string): Promise<void> {
     this.store.delete(sessionId);
   }
+
+  async loadWithStatus(sessionId: string): Promise<LoadResult> {
+    return { history: await this.load(sessionId), error: false };
+  }
 }

package/src/prompt-utils.ts

@@ -0,0 +1,12 @@
+/** Max characters allowed for heartbeat content to prevent context bloat. */
+export const MAX_HEARTBEAT_CHARS = 2000;
+
+/** Max characters allowed for memory content to prevent context bloat. */
+export const MAX_MEMORY_CHARS = 4000;
+
+/** Clamp content to a max character count, appending a truncation marker. */
+export function clampContent(content: string, maxChars: number): string {
+  const trimmed = content.trim();
+  if (trimmed.length <= maxChars) return trimmed;
+  return trimmed.slice(0, maxChars).trimEnd() + "\n...[truncated]";
+}