@epochtm/sdk 0.1.4

package/README.md

@@ -0,0 +1,60 @@
+# `@epochtm/sdk`
+
+Epoch TypeScript SDK for institution runtime continuity in agentic products.
+
+Use the SDK to turn model turns into structured memory contracts and inject continuity context before execution.
+
+## Why teams use it
+
+- Build an institution runtime for agents, not a chat-memory patch
+- Persist structured memory contracts after each turn
+- Inject context before model runs with inspectable behavior
+- Keep continuity portable across SDK, MCP, and HTTP flows
+
+## Install
+
+```bash
+npm i @epochtm/sdk
+```
+
+## Quickstart
+
+```ts
+import { createEpochClient } from "@epochtm/sdk";
+
+const epoch = createEpochClient({
+  apiKey: process.env.EPOCH_API_KEY!,
+  baseUrl: "https://api.memoryostm.dev",
+});
+
+const pre = await memory.beforeModel({
+  userId: "u_123",
+  question: "What should I build next?",
+  project: "memoryos",
+});
+
+await memory.afterModel({
+  userId: "u_123",
+  threadId: "thread-1",
+  contract: {
+    goal: "Ship MCP contract support",
+    decisions: ["Use contract-only ingest path in afterModel"],
+    next_actions: ["Add MCP + SDK contract tests"],
+  },
+  enforceContract: true,
+});
+```
+
+## APIs
+
+- `beforeModel(input)` for retrieval/resume context injection
+- `afterModel(input)` for message or contract ingest
+- `resume(input)` for project continuity summaries
+- `handoff(input)` for human/agent handoff packages
+
+## Notes
+
+- `afterModel` requires a non-empty `message` or a `contract`
+- `afterModel` returns `contractFieldCount` when contract fields are present
+- `afterModel` returns backend `traceId` for per-run tracing
+- `afterModel` returns `governanceApplied` with effective mode, TTL, redaction, and pinning

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { AfterModelInput, AfterModelResult, BeforeModelInput, BeforeModelResult, HandoffInput, HandoffResult, MemoryIgnitionBriefInput, MemoryIgnitionActionInput, MemoryIgnitionActionResult, MemoryIgnitionHandoffInput, MemoryIgnitionOutcomeInput, MemoryIgnitionRiskCheckInput, MemoryIgnitionRiskCheckResult, MemoryIgnitionSendNowInput, MemoryIgnitionSendNowResult, MemoryIgnitionStandardInheritancePackage, MemoryExperienceFailurePatternsResult, MemoryExperienceLessonsResult, MemoryExperienceQueryInput, MemoryExperienceRootCausesResult, MemoryExperienceRecommendationResult, MemoryExperienceSimilarityResult, MemoryExperienceSearchResult, MemoryTraceProofResult, EpochConfig, ResumeInput, ResumeResult } from "./types";
+export declare class EpochClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: EpochConfig);
+    private request;
+    /**
+     * Create the standard MemoryIgnition inheritance package before an agent acts.
+     */
+    createBrief(input: MemoryIgnitionBriefInput): Promise<BeforeModelResult>;
+    /**
+     * Return only the canonical Standard Inheritance Package that API, SDK, and MCP agents should consume.
+     */
+    createInheritancePackage(input: MemoryIgnitionBriefInput): Promise<MemoryIgnitionStandardInheritancePackage>;
+    /**
+     * Format and record a Send Now event for a target agent or runtime.
+     */
+    sendNow(input: MemoryIgnitionSendNowInput): Promise<MemoryIgnitionSendNowResult>;
+    /**
+     * Prepare and guard one proposed action before the agent uses a tool or edits files.
+     */
+    beforeAction(input: MemoryIgnitionActionInput): Promise<MemoryIgnitionActionResult>;
+    /**
+     * Re-check risk while an agent is acting, using current files/action/tool context.
+     */
+    duringAction(input: MemoryIgnitionActionInput): Promise<MemoryIgnitionActionResult>;
+    /**
+     * Check risk, approvals, required tests, and trace proof before tool use.
+     */
+    riskCheck(input: MemoryIgnitionRiskCheckInput): Promise<MemoryIgnitionRiskCheckResult>;
+    /**
+     * Save an agent outcome so future agents inherit what worked and failed.
+     */
+    saveOutcome(input: MemoryIgnitionOutcomeInput): Promise<AfterModelResult>;
+    /**
+     * Create a MemoryIgnition handoff package for another future agent.
+     */
+    createHandoff(input: MemoryIgnitionHandoffInput): Promise<HandoffResult>;
+    /**
+     * Inspect why a memory can be inherited.
+     */
+    getTraceProof(memoryId: string): Promise<MemoryTraceProofResult>;
+    private buildExperienceQueryPath;
+    /**
+     * Search verified Mission Control experiences.
+     */
+    searchExperiences(input?: MemoryExperienceQueryInput): Promise<MemoryExperienceSearchResult>;
+    /**
+     * List reusable lessons extracted from verified PR missions.
+     */
+    listExperienceLessons(input?: MemoryExperienceQueryInput): Promise<MemoryExperienceLessonsResult>;
+    /**
+     * List recurring failure patterns extracted from verified PR missions.
+     */
+    listFailurePatterns(input?: MemoryExperienceQueryInput): Promise<MemoryExperienceFailurePatternsResult>;
+    /**
+     * List root causes extracted from verified PR missions.
+     */
+    listRootCauses(input?: MemoryExperienceQueryInput): Promise<MemoryExperienceRootCausesResult>;
+    /**
+     * Find similar verified experiences to a specific mission or query.
+     */
+    findSimilarExperiences(input?: MemoryExperienceQueryInput & {
+        experienceId?: string;
+        repository?: string;
+    }): Promise<MemoryExperienceSimilarityResult>;
+    /**
+     * Build experience-backed recommendations for the next verification or fix.
+     */
+    getExperienceRecommendations(input?: MemoryExperienceQueryInput & {
+        repository?: string;
+    }): Promise<MemoryExperienceRecommendationResult>;
+    /**
+     * Creates the standard MemoryIgnition inheritance package before calling an agent.
+     */
+    beforeModel(input: BeforeModelInput): Promise<BeforeModelResult>;
+    /**
+     * Processes messages after the LLM response to extract and save memories.
+     */
+    afterModel(input: AfterModelInput): Promise<AfterModelResult>;
+    /**
+     * Specific endpoint for resuming a project thread.
+     */
+    resume(input: ResumeInput): Promise<ResumeResult>;
+    /**
+     * Specific endpoint for generating a handoff.
+     */
+    handoff(input: HandoffInput): Promise<HandoffResult>;
+}
+export declare function createEpochClient(config: EpochConfig): EpochClient;

package/dist/index.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EpochClient = void 0;
+exports.createEpochClient = createEpochClient;
+class EpochClient {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl ?? "http://localhost:3011").replace(/\/$/, "");
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            ...options.headers,
+        };
+        const response = await fetch(url, {
+            ...options,
+            headers,
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ message: "Unknown error" }));
+            throw new Error(`MemoryOS API Error: ${error.message || response.statusText}`);
+        }
+        const result = await response.json();
+        return result.data ?? result;
+    }
+    /**
+     * Create the standard MemoryIgnition inheritance package before an agent acts.
+     */
+    async createBrief(input) {
+        return this.request("/api/memory/memoryignition/brief", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Return only the canonical Standard Inheritance Package that API, SDK, and MCP agents should consume.
+     */
+    async createInheritancePackage(input) {
+        const brief = await this.createBrief(input);
+        return brief.standard_inheritance_package;
+    }
+    /**
+     * Format and record a Send Now event for a target agent or runtime.
+     */
+    async sendNow(input) {
+        return this.request("/api/memory/memoryignition/send-now", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Prepare and guard one proposed action before the agent uses a tool or edits files.
+     */
+    async beforeAction(input) {
+        return this.request("/api/memory/memoryignition/before-action", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Re-check risk while an agent is acting, using current files/action/tool context.
+     */
+    async duringAction(input) {
+        return this.request("/api/memory/memoryignition/during-action", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Check risk, approvals, required tests, and trace proof before tool use.
+     */
+    async riskCheck(input) {
+        return this.request("/api/memory/memoryignition/risk-check", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Save an agent outcome so future agents inherit what worked and failed.
+     */
+    async saveOutcome(input) {
+        return this.request("/api/memory/memoryignition/outcome", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Create a MemoryIgnition handoff package for another future agent.
+     */
+    async createHandoff(input) {
+        return this.request("/api/memory/memoryignition/handoff", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Inspect why a memory can be inherited.
+     */
+    async getTraceProof(memoryId) {
+        return this.request(`/api/memory/memory/${encodeURIComponent(memoryId)}/trace-proof`);
+    }
+    buildExperienceQueryPath(path, input = {}) {
+        const params = new URLSearchParams();
+        if (typeof input.query === "string" && input.query.trim().length > 0) {
+            params.set("query", input.query.trim());
+        }
+        if (typeof input.limit === "number" && Number.isFinite(input.limit)) {
+            params.set("limit", String(input.limit));
+        }
+        if (input.verdict) {
+            params.set("verdict", input.verdict);
+        }
+        const queryString = params.toString();
+        return queryString.length > 0 ? `${path}?${queryString}` : path;
+    }
+    /**
+     * Search verified Mission Control experiences.
+     */
+    async searchExperiences(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/search", input));
+    }
+    /**
+     * List reusable lessons extracted from verified PR missions.
+     */
+    async listExperienceLessons(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/lessons", input));
+    }
+    /**
+     * List recurring failure patterns extracted from verified PR missions.
+     */
+    async listFailurePatterns(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/failure-patterns", input));
+    }
+    /**
+     * List root causes extracted from verified PR missions.
+     */
+    async listRootCauses(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/root-causes", input));
+    }
+    /**
+     * Find similar verified experiences to a specific mission or query.
+     */
+    async findSimilarExperiences(input = {}) {
+        const path = this.buildExperienceQueryPath("/api/experience/similar", input);
+        const params = new URLSearchParams(path.includes("?") ? path.split("?")[1] : "");
+        if (typeof input.experienceId === "string" && input.experienceId.trim().length > 0) {
+            params.set("experienceId", input.experienceId.trim());
+        }
+        if (typeof input.repository === "string" && input.repository.trim().length > 0) {
+            params.set("repository", input.repository.trim());
+        }
+        const query = params.toString();
+        return this.request(query.length > 0 ? `/api/experience/similar?${query}` : "/api/experience/similar");
+    }
+    /**
+     * Build experience-backed recommendations for the next verification or fix.
+     */
+    async getExperienceRecommendations(input = {}) {
+        const path = this.buildExperienceQueryPath("/api/experience/recommendations", input);
+        const params = new URLSearchParams(path.includes("?") ? path.split("?")[1] : "");
+        if (typeof input.repository === "string" && input.repository.trim().length > 0) {
+            params.set("repository", input.repository.trim());
+        }
+        const query = params.toString();
+        return this.request(query.length > 0 ? `/api/experience/recommendations?${query}` : "/api/experience/recommendations");
+    }
+    /**
+     * Creates the standard MemoryIgnition inheritance package before calling an agent.
+     */
+    async beforeModel(input) {
+        return this.createBrief(input);
+    }
+    /**
+     * Processes messages after the LLM response to extract and save memories.
+     */
+    async afterModel(input) {
+        const hasMessage = typeof input.message === "string" && input.message.trim().length > 0;
+        const hasContract = Boolean(input.contract);
+        const hasOutcome = Boolean(input.outcome?.trim() || input.modelResponse?.trim());
+        if (!hasMessage && !hasContract && !hasOutcome) {
+            throw new Error("afterModel requires a non-empty message, outcome, model response, or memory contract.");
+        }
+        return this.saveOutcome(input);
+    }
+    /**
+     * Specific endpoint for resuming a project thread.
+     */
+    async resume(input) {
+        return this.request("/api/v1/memory/resume", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Specific endpoint for generating a handoff.
+     */
+    async handoff(input) {
+        return this.request("/api/v1/memory/handoff", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+}
+exports.EpochClient = EpochClient;
+function createEpochClient(config) {
+    return new EpochClient(config);
+}

package/dist/index.mjs

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EpochClient = void 0;
+exports.createEpochClient = createEpochClient;
+class EpochClient {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl ?? "http://localhost:3011").replace(/\/$/, "");
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            ...options.headers,
+        };
+        const response = await fetch(url, {
+            ...options,
+            headers,
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ message: "Unknown error" }));
+            throw new Error(`MemoryOS API Error: ${error.message || response.statusText}`);
+        }
+        const result = await response.json();
+        return result.data ?? result;
+    }
+    /**
+     * Create the standard MemoryIgnition inheritance package before an agent acts.
+     */
+    async createBrief(input) {
+        return this.request("/api/memory/memoryignition/brief", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Return only the canonical Standard Inheritance Package that API, SDK, and MCP agents should consume.
+     */
+    async createInheritancePackage(input) {
+        const brief = await this.createBrief(input);
+        return brief.standard_inheritance_package;
+    }
+    /**
+     * Format and record a Send Now event for a target agent or runtime.
+     */
+    async sendNow(input) {
+        return this.request("/api/memory/memoryignition/send-now", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Prepare and guard one proposed action before the agent uses a tool or edits files.
+     */
+    async beforeAction(input) {
+        return this.request("/api/memory/memoryignition/before-action", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Re-check risk while an agent is acting, using current files/action/tool context.
+     */
+    async duringAction(input) {
+        return this.request("/api/memory/memoryignition/during-action", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Check risk, approvals, required tests, and trace proof before tool use.
+     */
+    async riskCheck(input) {
+        return this.request("/api/memory/memoryignition/risk-check", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Save an agent outcome so future agents inherit what worked and failed.
+     */
+    async saveOutcome(input) {
+        return this.request("/api/memory/memoryignition/outcome", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Create a MemoryIgnition handoff package for another future agent.
+     */
+    async createHandoff(input) {
+        return this.request("/api/memory/memoryignition/handoff", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Inspect why a memory can be inherited.
+     */
+    async getTraceProof(memoryId) {
+        return this.request(`/api/memory/memory/${encodeURIComponent(memoryId)}/trace-proof`);
+    }
+    buildExperienceQueryPath(path, input = {}) {
+        const params = new URLSearchParams();
+        if (typeof input.query === "string" && input.query.trim().length > 0) {
+            params.set("query", input.query.trim());
+        }
+        if (typeof input.limit === "number" && Number.isFinite(input.limit)) {
+            params.set("limit", String(input.limit));
+        }
+        if (input.verdict) {
+            params.set("verdict", input.verdict);
+        }
+        const queryString = params.toString();
+        return queryString.length > 0 ? `${path}?${queryString}` : path;
+    }
+    /**
+     * Search verified Mission Control experiences.
+     */
+    async searchExperiences(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/search", input));
+    }
+    /**
+     * List reusable lessons extracted from verified PR missions.
+     */
+    async listExperienceLessons(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/lessons", input));
+    }
+    /**
+     * List recurring failure patterns extracted from verified PR missions.
+     */
+    async listFailurePatterns(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/failure-patterns", input));
+    }
+    /**
+     * List root causes extracted from verified PR missions.
+     */
+    async listRootCauses(input = {}) {
+        return this.request(this.buildExperienceQueryPath("/api/experience/root-causes", input));
+    }
+    /**
+     * Find similar verified experiences to a specific mission or query.
+     */
+    async findSimilarExperiences(input = {}) {
+        const path = this.buildExperienceQueryPath("/api/experience/similar", input);
+        const params = new URLSearchParams(path.includes("?") ? path.split("?")[1] : "");
+        if (typeof input.experienceId === "string" && input.experienceId.trim().length > 0) {
+            params.set("experienceId", input.experienceId.trim());
+        }
+        if (typeof input.repository === "string" && input.repository.trim().length > 0) {
+            params.set("repository", input.repository.trim());
+        }
+        const query = params.toString();
+        return this.request(query.length > 0 ? `/api/experience/similar?${query}` : "/api/experience/similar");
+    }
+    /**
+     * Build experience-backed recommendations for the next verification or fix.
+     */
+    async getExperienceRecommendations(input = {}) {
+        const path = this.buildExperienceQueryPath("/api/experience/recommendations", input);
+        const params = new URLSearchParams(path.includes("?") ? path.split("?")[1] : "");
+        if (typeof input.repository === "string" && input.repository.trim().length > 0) {
+            params.set("repository", input.repository.trim());
+        }
+        const query = params.toString();
+        return this.request(query.length > 0 ? `/api/experience/recommendations?${query}` : "/api/experience/recommendations");
+    }
+    /**
+     * Creates the standard MemoryIgnition inheritance package before calling an agent.
+     */
+    async beforeModel(input) {
+        return this.createBrief(input);
+    }
+    /**
+     * Processes messages after the LLM response to extract and save memories.
+     */
+    async afterModel(input) {
+        const hasMessage = typeof input.message === "string" && input.message.trim().length > 0;
+        const hasContract = Boolean(input.contract);
+        const hasOutcome = Boolean(input.outcome?.trim() || input.modelResponse?.trim());
+        if (!hasMessage && !hasContract && !hasOutcome) {
+            throw new Error("afterModel requires a non-empty message, outcome, model response, or memory contract.");
+        }
+        return this.saveOutcome(input);
+    }
+    /**
+     * Specific endpoint for resuming a project thread.
+     */
+    async resume(input) {
+        return this.request("/api/v1/memory/resume", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+    /**
+     * Specific endpoint for generating a handoff.
+     */
+    async handoff(input) {
+        return this.request("/api/v1/memory/handoff", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
+}
+exports.EpochClient = EpochClient;
+function createEpochClient(config) {
+    return new EpochClient(config);
+}