@agent-dreamer/sdk 0.0.3

package/README.md

@@ -0,0 +1,235 @@
+# @agent-dreamer/sdk
+
+Agent Memory TypeScript SDK 用于让 Node.js / TypeScript Agent 接入外部记忆服务。它封装了 session、memory event、记忆查询、短记忆生成和长记忆整理接口，并提供轻量的 `AgentMemorySession` 接入层。
+
+## 安装
+
+```bash
+npm install @agent-dreamer/sdk
+```
+
+本地开发时可以从源码安装依赖：
+
+```bash
+cd sdk/typescript
+npm install
+npm run build
+```
+
+## 创建 Client
+
+```ts
+import { AgentMemoryClient } from "@agent-dreamer/sdk";
+
+const client = new AgentMemoryClient({
+  baseUrl: process.env.AGENT_MEMORY_BASE_URL!,
+  apiKey: process.env.AGENT_MEMORY_API_KEY!,
+});
+```
+
+常用环境变量：
+
+```bash
+export AGENT_MEMORY_BASE_URL='http://localhost:8080'
+export AGENT_MEMORY_API_KEY='<workspace api key>'
+export AGENT_MEMORY_AGENT_INSTANCE_ID='<agent_instance_id>'
+```
+
+## 创建或复用 Session
+
+每个 Agent 会话开始时先创建或复用 session。`external_session_id` 是调用方自己的会话 ID，同一个 Agent 下重复传入会复用同一个服务端 session。
+
+```ts
+const session = await client.createSession({
+  agent_instance_id: process.env.AGENT_MEMORY_AGENT_INSTANCE_ID!,
+  external_session_id: "typescript-task-20260616-001",
+  metadata: {
+    source: "typescript-agent",
+  },
+});
+
+console.log("session_id:", session.session_id);
+```
+
+## 写入 Memory Event
+
+Agent 每轮推理和工具执行过程都应该写入 memory event。事件是记忆生成的事实来源。
+
+```ts
+const event = await client.recordEvent({
+  session_id: session.session_id,
+  external_thread_id: "main",
+  event_id: "evt-user-001",
+  event_type: "message",
+  actor: "user",
+  status: "success",
+  summary: "用户要求继续 SDK 接入任务。",
+  payload: {
+    text: "请继续 SDK 接入任务",
+  },
+});
+
+console.log("thread_id:", event.thread_id);
+```
+
+常用事件类型：
+
+| event_type | 适合场景 |
+| --- | --- |
+| `message` | 用户消息、Agent 回复 |
+| `tool_call` | 调用工具前记录工具名和参数摘要 |
+| `tool_result` | 工具执行完成后记录结果、状态、错误码 |
+| `planner_update` | 计划、待办、阶段性决策变化 |
+| `task_state` | 任务开始、暂停、完成、失败、阻塞 |
+| `artifact_change` | 文件、代码、文档、报告等产物变化 |
+| `correction_signal` | 用户纠错或要求修正此前信息 |
+
+工具失败事件建议填写 `status`、`error_code` 和 `retryable`。
+
+```ts
+await client.recordEvent({
+  session_id: session.session_id,
+  event_id: "evt-tool-result-001",
+  event_type: "tool_result",
+  actor: "tool",
+  status: "error",
+  tool_name: "npm test",
+  error_code: "TEST_FAILED",
+  retryable: true,
+  summary: "npm test 执行失败。",
+  payload: {
+    command: "npm test",
+    exit_code: 1,
+  },
+});
+```
+
+## 查询记忆
+
+每轮 Agent 推理前建议调用一次记忆查询，获取少量可注入上下文。
+
+```ts
+import { formatMemoryContext } from "@agent-dreamer/sdk";
+
+const response = await client.queryMemories({
+  session_id: session.session_id,
+  thread_id: event.thread_id,
+  query_text: "继续 SDK 接入任务，需要恢复当前进展和注意事项",
+  query_intent: "execution_help",
+  desired_memory_types: [
+    "task_whiteboard",
+    "tool_digest",
+    "failure_digest",
+    "procedure",
+  ],
+  limit: 8,
+  event_limit: 3,
+});
+
+const promptContext = formatMemoryContext(response);
+console.log(promptContext);
+```
+
+常用查询意图：
+
+| query_intent | 适合场景 |
+| --- | --- |
+| `execution_help` | 继续任务、写代码、调用工具、排错 |
+| `policy_lookup` | 查询规则、约束、团队规范 |
+| `preference_lookup` | 查询用户偏好、输出风格 |
+| `factual_lookup` | 查询稳定事实、项目背景 |
+| `broad_context` | 不确定意图时综合召回 |
+
+## 触发短记忆生成
+
+短记忆用于整理当前 session/thread 的近期上下文，例如任务白板、工具结果摘要、失败摘要。
+
+适合触发时机：
+
+- 用户消息写入后，尤其是用户给出新目标或新约束。
+- 工具调用或工具结果写入后。
+- 一个阶段性步骤完成后。
+- 出现错误、超时、取消、用户纠错后。
+
+```ts
+const run = await client.generateShortMemory({
+  session_id: session.session_id,
+  thread_id: event.thread_id,
+  trigger_source: "thread_end",
+  hints: {
+    reason: "阶段完成后刷新任务白板",
+  },
+});
+
+console.log("short memory queued:", run.run_ids);
+```
+
+`status=queued` 表示任务已入队。需要 worker 消费完成后，新的短记忆才会出现在查询结果中。
+
+## 触发长记忆整理
+
+长记忆用于沉淀跨会话可复用的信息，例如事实、偏好、流程和规则。
+
+适合触发时机：
+
+- 会话结束时。
+- 一个完整任务完成后。
+- 用户明确表达稳定偏好时。
+- 形成可复用流程、项目事实、团队规则时。
+- 不建议对临时、未经确认、明显只对当前轮有效的信息触发长期整理。
+
+```ts
+const run = await client.consolidateLongMemory({
+  session_id: session.session_id,
+  trigger_source: "session_end",
+  hints: {
+    reason: "会话结束后沉淀长期记忆",
+  },
+});
+
+console.log("long memory queued:", run.run_ids);
+```
+
+## 使用 AgentMemorySession 简化接入
+
+`AgentMemorySession` 会自动创建 session、写标准事件，并缓存服务端返回的 `thread_id`，后续查询和生成会自动带上线程上下文。
+
+```ts
+import { AgentMemoryClient, AgentMemorySession } from "@agent-dreamer/sdk";
+
+const client = new AgentMemoryClient({
+  baseUrl: process.env.AGENT_MEMORY_BASE_URL!,
+  apiKey: process.env.AGENT_MEMORY_API_KEY!,
+});
+
+const agentMemory = new AgentMemorySession(client, {
+  agentInstanceId: process.env.AGENT_MEMORY_AGENT_INSTANCE_ID!,
+  externalSessionId: "typescript-task-20260616-001",
+  externalThreadId: "main",
+});
+
+await agentMemory.recordUserMessage("请继续 SDK 接入任务。");
+
+const shortRun = await agentMemory.generateShortMemory("thread_end");
+console.log("short memory queued:", shortRun.run_ids);
+
+const memoryContext = await agentMemory.queryContext({
+  queryText: "继续 SDK 接入任务",
+  queryIntent: "execution_help",
+  desiredMemoryTypes: ["task_whiteboard", "tool_digest", "procedure"],
+  limit: 6,
+  eventLimit: 3,
+});
+
+console.log(memoryContext.text);
+```
+
+## 查看示例
+
+```bash
+cd sdk/typescript
+npm install
+npm run build
+npx tsx examples/basic.ts
+npx tsx examples/agent_loop.ts
+```

package/dist/adapter.d.ts

@@ -0,0 +1,48 @@
+import { AgentMemoryClient } from "./client.js";
+import { GenerateMemoryResp, MemoryEventItem, MemoryItem, MemoryQueryResp, RecordEventResp } from "./types.js";
+export interface AgentSessionConfig {
+    agentInstanceId: string;
+    externalSessionId: string;
+    sessionId?: string;
+    threadId?: string;
+    externalThreadId?: string;
+    metadata?: unknown;
+    threadMetadata?: unknown;
+}
+export interface QueryContextReq {
+    queryText: string;
+    queryIntent?: string;
+    desiredMemoryTypes?: string[];
+    limit?: number;
+    eventLimit?: number;
+    includeArchived?: boolean;
+}
+export interface MemoryContext {
+    text: string;
+    response: MemoryQueryResp;
+    items: MemoryItem[];
+    memoryEvents: MemoryEventItem[];
+}
+export declare class AgentMemorySession {
+    private client;
+    private config;
+    constructor(client: AgentMemoryClient, config: AgentSessionConfig);
+    ensureSession(): Promise<string>;
+    recordUserMessage(content: string): Promise<RecordEventResp>;
+    recordAssistantMessage(content: string): Promise<RecordEventResp>;
+    recordToolCall(toolName: string, summary: string, payload: unknown): Promise<RecordEventResp>;
+    recordToolResult(toolName: string, status: string, summary: string, payload: unknown, options?: {
+        errorCode?: string;
+        retryable?: boolean;
+    }): Promise<RecordEventResp>;
+    recordPlannerUpdate(summary: string, payload: unknown): Promise<RecordEventResp>;
+    recordTaskState(summary: string, payload: unknown): Promise<RecordEventResp>;
+    recordArtifactChange(summary: string, payload: unknown): Promise<RecordEventResp>;
+    recordCorrectionSignal(summary: string, payload: unknown): Promise<RecordEventResp>;
+    queryContext(req: QueryContextReq): Promise<MemoryContext>;
+    generateShortMemory(triggerSource?: string): Promise<GenerateMemoryResp>;
+    consolidateLongMemory(triggerSource?: string): Promise<GenerateMemoryResp>;
+    private record;
+    private captureThreadId;
+}
+export declare function formatMemoryContext(response: MemoryQueryResp): string;

package/dist/adapter.js

@@ -0,0 +1,165 @@
+import { randomBytes } from "node:crypto";
+import { EVENT_ACTOR_ASSISTANT, EVENT_ACTOR_SYSTEM, EVENT_ACTOR_TOOL, EVENT_ACTOR_USER, EVENT_STATUS_SUCCESS, MEMORY_TYPE_FACT, MEMORY_TYPE_POLICY, MEMORY_TYPE_PREFERENCE, MEMORY_TYPE_PROCEDURE, TRIGGER_SOURCE_MANUAL, } from "./types.js";
+export class AgentMemorySession {
+    client;
+    config;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    async ensureSession() {
+        if (this.config.sessionId)
+            return this.config.sessionId;
+        const resp = await this.client.createSession({
+            agent_instance_id: this.config.agentInstanceId,
+            external_session_id: this.config.externalSessionId,
+            metadata: this.config.metadata,
+        });
+        this.config.sessionId = resp.session_id;
+        return resp.session_id;
+    }
+    recordUserMessage(content) {
+        return this.record("message", EVENT_ACTOR_USER, content, { text: content });
+    }
+    recordAssistantMessage(content) {
+        return this.record("message", EVENT_ACTOR_ASSISTANT, content, { text: content });
+    }
+    recordToolCall(toolName, summary, payload) {
+        return this.record("tool_call", EVENT_ACTOR_TOOL, summary, payload, toolName);
+    }
+    async recordToolResult(toolName, status, summary, payload, options = {}) {
+        const sessionId = await this.ensureSession();
+        const result = await this.client.recordEvent({
+            session_id: sessionId,
+            external_thread_id: this.config.externalThreadId,
+            thread_metadata: this.config.threadMetadata,
+            event_id: newEventId("tool-result"),
+            event_type: "tool_result",
+            actor: EVENT_ACTOR_TOOL,
+            summary,
+            status,
+            tool_name: toolName,
+            error_code: options.errorCode,
+            retryable: options.retryable,
+            payload,
+        });
+        this.captureThreadId(result.thread_id);
+        return result;
+    }
+    recordPlannerUpdate(summary, payload) {
+        return this.record("planner_update", EVENT_ACTOR_SYSTEM, summary, payload);
+    }
+    recordTaskState(summary, payload) {
+        return this.record("task_state", EVENT_ACTOR_SYSTEM, summary, payload);
+    }
+    recordArtifactChange(summary, payload) {
+        return this.record("artifact_change", EVENT_ACTOR_SYSTEM, summary, payload);
+    }
+    recordCorrectionSignal(summary, payload) {
+        return this.record("correction_signal", EVENT_ACTOR_USER, summary, payload);
+    }
+    async queryContext(req) {
+        const sessionId = await this.ensureSession();
+        const response = await this.client.queryMemories({
+            session_id: sessionId,
+            thread_id: this.config.threadId,
+            query_text: req.queryText,
+            query_intent: req.queryIntent,
+            desired_memory_types: req.desiredMemoryTypes,
+            include_archived: req.includeArchived,
+            limit: req.limit,
+            event_limit: req.eventLimit,
+        });
+        return {
+            text: formatMemoryContext(response),
+            response,
+            items: response.result.items,
+            memoryEvents: response.result.memory_events,
+        };
+    }
+    async generateShortMemory(triggerSource = TRIGGER_SOURCE_MANUAL) {
+        return this.client.generateShortMemory({
+            session_id: await this.ensureSession(),
+            thread_id: this.config.threadId,
+            trigger_source: triggerSource,
+        });
+    }
+    async consolidateLongMemory(triggerSource = TRIGGER_SOURCE_MANUAL) {
+        return this.client.consolidateLongMemory({
+            session_id: await this.ensureSession(),
+            thread_id: this.config.threadId,
+            trigger_source: triggerSource,
+        });
+    }
+    async record(eventType, actor, summary, payload, toolName) {
+        const sessionId = await this.ensureSession();
+        const result = await this.client.recordEvent({
+            session_id: sessionId,
+            external_thread_id: this.config.externalThreadId,
+            thread_metadata: this.config.threadMetadata,
+            event_id: newEventId(eventType),
+            event_type: eventType,
+            actor,
+            summary,
+            status: EVENT_STATUS_SUCCESS,
+            tool_name: toolName,
+            payload,
+        });
+        this.captureThreadId(result.thread_id);
+        return result;
+    }
+    captureThreadId(threadId) {
+        if (threadId)
+            this.config.threadId = threadId;
+    }
+}
+export function formatMemoryContext(response) {
+    const lines = [];
+    const used = new Set();
+    const groups = [
+        ["Policy memories", (item) => item.memory_type === MEMORY_TYPE_POLICY],
+        ["Procedure memories", (item) => item.memory_type === MEMORY_TYPE_PROCEDURE],
+        ["Preference memories", (item) => item.memory_type === MEMORY_TYPE_PREFERENCE],
+        ["Fact memories", (item) => item.memory_type === MEMORY_TYPE_FACT],
+        ["Short memories", (item) => item.kind === "short"],
+    ];
+    for (const [title, predicate] of groups) {
+        const selected = response.result.items.filter((item) => !used.has(item.id) && predicate(item));
+        if (!selected.length)
+            continue;
+        appendSection(lines, title);
+        for (const item of selected) {
+            used.add(item.id);
+            lines.push(formatItem(item));
+        }
+    }
+    const other = response.result.items.filter((item) => !used.has(item.id));
+    if (other.length) {
+        appendSection(lines, "Other memories");
+        lines.push(...other.map(formatItem));
+    }
+    if (response.result.memory_events.length) {
+        appendSection(lines, "Recent raw events");
+        lines.push(...response.result.memory_events.map((event) => `- [${event.event_type}/${event.actor || ""}] ${event.summary || ""}`));
+    }
+    return lines.join("\n").trim();
+}
+function appendSection(lines, title) {
+    if (lines.length)
+        lines.push("");
+    lines.push(`## ${title}`);
+}
+function formatItem(item) {
+    const markers = [];
+    if (item.conflict_state && item.conflict_state !== "none")
+        markers.push(`conflict=${item.conflict_state}`);
+    if (item.archived_at)
+        markers.push("archived");
+    if (item.confidence > 0 && item.confidence < 0.5)
+        markers.push("low_confidence");
+    const marker = markers.length ? ` [${markers.join(",")}]` : "";
+    return `- (${item.scope}/${item.memory_type} confidence=${item.confidence.toFixed(2)}${marker}) ${item.content}`;
+}
+function newEventId(prefix) {
+    return `${prefix}-${randomBytes(8).toString("hex")}`;
+}

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import { AgentMemoryClientConfig, CreateSessionReq, CreateSessionResp, GenerateMemoryReq, GenerateMemoryResp, ListRunsReq, MemoryQueryReq, MemoryQueryResp, RecordEventReq, RecordEventResp } from "./types.js";
+export declare class AgentMemoryApiError extends Error {
+    statusCode: number;
+    traceId?: string;
+    responseBody: string;
+    constructor(statusCode: number, message: string, traceId?: string, responseBody?: string);
+}
+export declare class AgentMemoryClient {
+    private baseUrl;
+    private apiKey;
+    private apiKeyHeader;
+    private timeoutMs;
+    private maxRetries;
+    private fetchImpl;
+    constructor(config: AgentMemoryClientConfig);
+    createSession(req: CreateSessionReq): Promise<CreateSessionResp>;
+    recordEvent(req: RecordEventReq): Promise<RecordEventResp>;
+    queryMemories(req: MemoryQueryReq): Promise<MemoryQueryResp>;
+    generateShortMemory(req: GenerateMemoryReq): Promise<GenerateMemoryResp>;
+    consolidateLongMemory(req: GenerateMemoryReq): Promise<GenerateMemoryResp>;
+    listMemoryGenerationRuns(req?: ListRunsReq): Promise<Record<string, unknown>>;
+    getMemoryGenerationRun(id: string): Promise<Record<string, unknown>>;
+    private request;
+    private requestOnce;
+}

package/dist/client.js

@@ -0,0 +1,142 @@
+import { TRIGGER_SOURCE_MANUAL, } from "./types.js";
+const DEFAULT_API_KEY_HEADER = "X-API-Key";
+export class AgentMemoryApiError extends Error {
+    statusCode;
+    traceId;
+    responseBody;
+    constructor(statusCode, message, traceId, responseBody = "") {
+        super(message);
+        this.name = "AgentMemoryApiError";
+        this.statusCode = statusCode;
+        this.traceId = traceId;
+        this.responseBody = responseBody;
+    }
+}
+export class AgentMemoryClient {
+    baseUrl;
+    apiKey;
+    apiKeyHeader;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    constructor(config) {
+        if (!config.baseUrl)
+            throw new Error("baseUrl is required");
+        if (!config.apiKey)
+            throw new Error("apiKey is required");
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.apiKey = config.apiKey;
+        this.apiKeyHeader = config.apiKeyHeader || DEFAULT_API_KEY_HEADER;
+        this.timeoutMs = config.timeoutMs || 10_000;
+        this.maxRetries = config.maxRetries ?? 3;
+        this.fetchImpl = config.fetchImpl || fetch;
+    }
+    createSession(req) {
+        return this.request("POST", "/v1/sessions", req);
+    }
+    recordEvent(req) {
+        return this.request("POST", "/v1/events", req);
+    }
+    queryMemories(req) {
+        return this.request("POST", "/v1/memory/query", req);
+    }
+    generateShortMemory(req) {
+        return this.request("POST", "/v1/memory/short/generate", normalizeGenerateReq(req));
+    }
+    consolidateLongMemory(req) {
+        return this.request("POST", "/v1/memory/long/consolidate", normalizeGenerateReq(req));
+    }
+    listMemoryGenerationRuns(req = {}) {
+        const query = new URLSearchParams();
+        for (const [key, value] of Object.entries(req)) {
+            if (value !== undefined && value !== null && value !== "")
+                query.set(key, String(value));
+        }
+        const suffix = query.size ? `?${query.toString()}` : "";
+        return this.request("GET", `/v1/memory/runs${suffix}`);
+    }
+    getMemoryGenerationRun(id) {
+        return this.request("GET", `/v1/memory/runs/${encodeURIComponent(id)}`);
+    }
+    async request(method, path, body) {
+        const payload = body === undefined ? undefined : JSON.stringify(compact(body));
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            if (attempt > 0)
+                await sleep(retryDelay(attempt));
+            try {
+                return await this.requestOnce(method, path, payload);
+            }
+            catch (error) {
+                lastError = error;
+                if (!(error instanceof AgentMemoryApiError) || !shouldRetry(error.statusCode))
+                    throw error;
+            }
+        }
+        throw lastError;
+    }
+    async requestOnce(method, path, payload) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchImpl(this.baseUrl + path, {
+                method,
+                body: payload,
+                signal: controller.signal,
+                headers: {
+                    [this.apiKeyHeader]: this.apiKey,
+                    Accept: "application/json",
+                    ...(payload ? { "Content-Type": "application/json" } : {}),
+                },
+            });
+            const raw = await response.text();
+            if (!response.ok) {
+                throw parseApiError(response.status, response.headers.get("X-Trace-Id") || undefined, raw);
+            }
+            return raw ? JSON.parse(raw) : undefined;
+        }
+        catch (error) {
+            if (error instanceof AgentMemoryApiError)
+                throw error;
+            throw new AgentMemoryApiError(0, error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+function normalizeGenerateReq(req) {
+    return { ...req, trigger_source: req.trigger_source || TRIGGER_SOURCE_MANUAL };
+}
+function parseApiError(statusCode, traceId, raw) {
+    let message = raw.trim();
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.error)
+            message = parsed.error;
+    }
+    catch {
+        // 保留原始响应文本作为错误信息。
+    }
+    return new AgentMemoryApiError(statusCode, message, traceId, raw);
+}
+function shouldRetry(statusCode) {
+    return statusCode === 0 || statusCode === 408 || statusCode === 429 || statusCode >= 500;
+}
+function retryDelay(attempt) {
+    const base = 100 * 2 ** Math.min(attempt - 1, 5);
+    return base + Math.random() * (base / 2);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function compact(value) {
+    if (Array.isArray(value))
+        return value.map(compact);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, nested]) => nested !== undefined && nested !== null)
+            .map(([key, nested]) => [key, compact(nested)]));
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./adapter.js";
+export * from "./client.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./adapter.js";
+export * from "./client.js";
+export * from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+export declare const MEMORY_TYPE_TIMELINE = "timeline";
+export declare const MEMORY_TYPE_TASK_WHITEBOARD = "task_whiteboard";
+export declare const MEMORY_TYPE_FAILURE_DIGEST = "failure_digest";
+export declare const MEMORY_TYPE_TOOL_DIGEST = "tool_digest";
+export declare const MEMORY_TYPE_FACT = "fact";
+export declare const MEMORY_TYPE_PREFERENCE = "preference";
+export declare const MEMORY_TYPE_PROCEDURE = "procedure";
+export declare const MEMORY_TYPE_POLICY = "policy";
+export declare const QUERY_INTENT_EXECUTION_HELP = "execution_help";
+export declare const QUERY_INTENT_BROAD_CONTEXT = "broad_context";
+export declare const EVENT_ACTOR_USER = "user";
+export declare const EVENT_ACTOR_ASSISTANT = "assistant";
+export declare const EVENT_ACTOR_TOOL = "tool";
+export declare const EVENT_ACTOR_SYSTEM = "system";
+export declare const EVENT_STATUS_SUCCESS = "success";
+export declare const EVENT_STATUS_ERROR = "error";
+export declare const EVENT_STATUS_TIMEOUT = "timeout";
+export declare const EVENT_STATUS_CANCELLED = "cancelled";
+export declare const TRIGGER_SOURCE_MANUAL = "manual";
+export declare const TRIGGER_SOURCE_SESSION_END = "session_end";
+export declare const TRIGGER_SOURCE_THREAD_END = "thread_end";
+export interface AgentMemoryClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    apiKeyHeader?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface CreateSessionReq {
+    agent_instance_id: string;
+    external_session_id: string;
+    metadata?: unknown;
+}
+export interface CreateSessionResp {
+    session_id: string;
+    agent_instance_id: string;
+    external_session_id: string;
+    started_at: string;
+}
+export interface RecordEventReq {
+    session_id: string;
+    event_id: string;
+    event_type: string;
+    payload: unknown;
+    external_thread_id?: string;
+    thread_metadata?: unknown;
+    actor?: string;
+    summary?: string;
+    status?: string;
+    tool_name?: string;
+    error_code?: string;
+    retryable?: boolean;
+    occurred_at?: string;
+}
+export interface RecordEventResp {
+    inserted: boolean;
+    thread_id?: string;
+}
+export interface GenerateMemoryReq {
+    session_id: string;
+    thread_id?: string;
+    strategy_pack_key?: string;
+    trigger_source?: string;
+    hints?: unknown;
+}
+export interface GenerateMemoryResp {
+    run_ids: string[];
+    strategy_ids: string[];
+    strategy_pack_key?: string;
+    trigger_source: string;
+    status: string;
+}
+export interface MemoryQueryReq {
+    session_id: string;
+    query_text: string;
+    thread_id?: string;
+    query_intent?: string;
+    desired_memory_types?: string[];
+    include_archived?: boolean;
+    limit?: number;
+    event_limit?: number;
+}
+export interface MemoryQueryResp {
+    scope_policy: {
+        order: string[];
+    };
+    query_profile: {
+        intent: string;
+        memory_type_priority: string[];
+        include_archived?: boolean;
+        rerank_weights?: Record<string, unknown>;
+    };
+    result: {
+        items: MemoryItem[];
+        memory_events: MemoryEventItem[];
+    };
+}
+export interface MemoryItem {
+    id: string;
+    kind: string;
+    scope: string;
+    memory_type: string;
+    title?: string | null;
+    content: string;
+    confidence: number;
+    quality_score?: number;
+    human_verified?: boolean;
+    conflict_state?: string;
+    strategy_id?: string;
+    created_at?: string;
+    updated_at?: string | null;
+    archived_at?: string | null;
+    score?: number;
+    reason_tags?: string[];
+}
+export interface MemoryEventItem {
+    id: number;
+    agent_instance_id: string;
+    session_id: string;
+    thread_id?: string | null;
+    event_id: string;
+    event_type: string;
+    actor?: string;
+    summary?: string;
+    status?: string;
+    tool_name?: string;
+    error_code?: string;
+    retryable?: boolean | null;
+    payload?: unknown;
+    occurred_at: string;
+    ingested_at: string;
+}
+export interface ListRunsReq {
+    kind?: string;
+    status?: string;
+    session_id?: string;
+    thread_id?: string;
+    limit?: number;
+    offset?: number;
+}

package/dist/types.js

@@ -0,0 +1,21 @@
+export const MEMORY_TYPE_TIMELINE = "timeline";
+export const MEMORY_TYPE_TASK_WHITEBOARD = "task_whiteboard";
+export const MEMORY_TYPE_FAILURE_DIGEST = "failure_digest";
+export const MEMORY_TYPE_TOOL_DIGEST = "tool_digest";
+export const MEMORY_TYPE_FACT = "fact";
+export const MEMORY_TYPE_PREFERENCE = "preference";
+export const MEMORY_TYPE_PROCEDURE = "procedure";
+export const MEMORY_TYPE_POLICY = "policy";
+export const QUERY_INTENT_EXECUTION_HELP = "execution_help";
+export const QUERY_INTENT_BROAD_CONTEXT = "broad_context";
+export const EVENT_ACTOR_USER = "user";
+export const EVENT_ACTOR_ASSISTANT = "assistant";
+export const EVENT_ACTOR_TOOL = "tool";
+export const EVENT_ACTOR_SYSTEM = "system";
+export const EVENT_STATUS_SUCCESS = "success";
+export const EVENT_STATUS_ERROR = "error";
+export const EVENT_STATUS_TIMEOUT = "timeout";
+export const EVENT_STATUS_CANCELLED = "cancelled";
+export const TRIGGER_SOURCE_MANUAL = "manual";
+export const TRIGGER_SOURCE_SESSION_END = "session_end";
+export const TRIGGER_SOURCE_THREAD_END = "thread_end";

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@agent-dreamer/sdk",
+  "version": "0.0.3",
+  "description": "Agent Memory HTTP SDK and lightweight Agent adapter",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "agent",
+    "memory",
+    "sdk"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "typescript": "^5.6.0"
+  }
+}