{"_rev":"5-a6996f261ac369cf2aa0a393381406ca","time":{"created":"2026-06-16T09:48:52.231Z","modified":"2026-06-16T09:48:52.789Z","0.0.1":"2026-06-16T09:30:57.226Z","0.0.2":"2026-06-16T09:46:13.273Z","0.0.3":"2026-06-16T09:48:52.571Z"},"_id":"@agent-dreamer/sdk","name":"@agent-dreamer/sdk","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.3":{"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","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"},"gitHead":"1dc99cbcf93d16b1034cb1b2fced39c70fda2abe","_id":"@agent-dreamer/sdk@0.0.3","_nodeVersion":"25.4.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-gdHlloD7sXHSej1nRIb3jrKnxH6J/wkShrylrM6AI3I0UmlZpSD+eTzGQQYZRFU5p8i++fl721GDqNGf5zYC4w==","shasum":"1b70e4e6020d50518883d9382ec3b8a2e1b86dee","tarball":"https://registry.npmjs.org/@agent-dreamer/sdk/-/sdk-0.0.3.tgz","fileCount":10,"unpackedSize":27340,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDbin3ZP/RhToaDEtbuHNv4ogIjQPFQrBtIp4FIobGU7wIgRuhlTVEEs3cpkbpoF2jsrZqVetQZGm3EmMLuJ4tppiA="}]},"_npmUser":{"name":"wangyang568279","email":"isyang.wang@gmail.com"},"directories":{},"maintainers":[{"name":"wangyang568279","email":"isyang.wang@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.0.3_1781603332408_0.3744842408588871"},"_hasShrinkwrap":false}},"maintainers":[{"name":"wangyang568279","email":"isyang.wang@gmail.com"}],"description":"Agent Memory HTTP SDK and lightweight Agent adapter","keywords":["agent","memory","sdk"],"license":"MIT","readme":"# @agent-dreamer/sdk\n\nAgent Memory TypeScript SDK 用于让 Node.js / TypeScript Agent 接入外部记忆服务。它封装了 session、memory event、记忆查询、短记忆生成和长记忆整理接口，并提供轻量的 `AgentMemorySession` 接入层。\n\n## 安装\n\n```bash\nnpm install @agent-dreamer/sdk\n```\n\n本地开发时可以从源码安装依赖：\n\n```bash\ncd sdk/typescript\nnpm install\nnpm run build\n```\n\n## 创建 Client\n\n```ts\nimport { AgentMemoryClient } from \"@agent-dreamer/sdk\";\n\nconst client = new AgentMemoryClient({\n  baseUrl: process.env.AGENT_MEMORY_BASE_URL!,\n  apiKey: process.env.AGENT_MEMORY_API_KEY!,\n});\n```\n\n常用环境变量：\n\n```bash\nexport AGENT_MEMORY_BASE_URL='http://localhost:8080'\nexport AGENT_MEMORY_API_KEY='<workspace api key>'\nexport AGENT_MEMORY_AGENT_INSTANCE_ID='<agent_instance_id>'\n```\n\n## 创建或复用 Session\n\n每个 Agent 会话开始时先创建或复用 session。`external_session_id` 是调用方自己的会话 ID，同一个 Agent 下重复传入会复用同一个服务端 session。\n\n```ts\nconst session = await client.createSession({\n  agent_instance_id: process.env.AGENT_MEMORY_AGENT_INSTANCE_ID!,\n  external_session_id: \"typescript-task-20260616-001\",\n  metadata: {\n    source: \"typescript-agent\",\n  },\n});\n\nconsole.log(\"session_id:\", session.session_id);\n```\n\n## 写入 Memory Event\n\nAgent 每轮推理和工具执行过程都应该写入 memory event。事件是记忆生成的事实来源。\n\n```ts\nconst event = await client.recordEvent({\n  session_id: session.session_id,\n  external_thread_id: \"main\",\n  event_id: \"evt-user-001\",\n  event_type: \"message\",\n  actor: \"user\",\n  status: \"success\",\n  summary: \"用户要求继续 SDK 接入任务。\",\n  payload: {\n    text: \"请继续 SDK 接入任务\",\n  },\n});\n\nconsole.log(\"thread_id:\", event.thread_id);\n```\n\n常用事件类型：\n\n| event_type | 适合场景 |\n| --- | --- |\n| `message` | 用户消息、Agent 回复 |\n| `tool_call` | 调用工具前记录工具名和参数摘要 |\n| `tool_result` | 工具执行完成后记录结果、状态、错误码 |\n| `planner_update` | 计划、待办、阶段性决策变化 |\n| `task_state` | 任务开始、暂停、完成、失败、阻塞 |\n| `artifact_change` | 文件、代码、文档、报告等产物变化 |\n| `correction_signal` | 用户纠错或要求修正此前信息 |\n\n工具失败事件建议填写 `status`、`error_code` 和 `retryable`。\n\n```ts\nawait client.recordEvent({\n  session_id: session.session_id,\n  event_id: \"evt-tool-result-001\",\n  event_type: \"tool_result\",\n  actor: \"tool\",\n  status: \"error\",\n  tool_name: \"npm test\",\n  error_code: \"TEST_FAILED\",\n  retryable: true,\n  summary: \"npm test 执行失败。\",\n  payload: {\n    command: \"npm test\",\n    exit_code: 1,\n  },\n});\n```\n\n## 查询记忆\n\n每轮 Agent 推理前建议调用一次记忆查询，获取少量可注入上下文。\n\n```ts\nimport { formatMemoryContext } from \"@agent-dreamer/sdk\";\n\nconst response = await client.queryMemories({\n  session_id: session.session_id,\n  thread_id: event.thread_id,\n  query_text: \"继续 SDK 接入任务，需要恢复当前进展和注意事项\",\n  query_intent: \"execution_help\",\n  desired_memory_types: [\n    \"task_whiteboard\",\n    \"tool_digest\",\n    \"failure_digest\",\n    \"procedure\",\n  ],\n  limit: 8,\n  event_limit: 3,\n});\n\nconst promptContext = formatMemoryContext(response);\nconsole.log(promptContext);\n```\n\n常用查询意图：\n\n| query_intent | 适合场景 |\n| --- | --- |\n| `execution_help` | 继续任务、写代码、调用工具、排错 |\n| `policy_lookup` | 查询规则、约束、团队规范 |\n| `preference_lookup` | 查询用户偏好、输出风格 |\n| `factual_lookup` | 查询稳定事实、项目背景 |\n| `broad_context` | 不确定意图时综合召回 |\n\n## 触发短记忆生成\n\n短记忆用于整理当前 session/thread 的近期上下文，例如任务白板、工具结果摘要、失败摘要。\n\n适合触发时机：\n\n- 用户消息写入后，尤其是用户给出新目标或新约束。\n- 工具调用或工具结果写入后。\n- 一个阶段性步骤完成后。\n- 出现错误、超时、取消、用户纠错后。\n\n```ts\nconst run = await client.generateShortMemory({\n  session_id: session.session_id,\n  thread_id: event.thread_id,\n  trigger_source: \"thread_end\",\n  hints: {\n    reason: \"阶段完成后刷新任务白板\",\n  },\n});\n\nconsole.log(\"short memory queued:\", run.run_ids);\n```\n\n`status=queued` 表示任务已入队。需要 worker 消费完成后，新的短记忆才会出现在查询结果中。\n\n## 触发长记忆整理\n\n长记忆用于沉淀跨会话可复用的信息，例如事实、偏好、流程和规则。\n\n适合触发时机：\n\n- 会话结束时。\n- 一个完整任务完成后。\n- 用户明确表达稳定偏好时。\n- 形成可复用流程、项目事实、团队规则时。\n- 不建议对临时、未经确认、明显只对当前轮有效的信息触发长期整理。\n\n```ts\nconst run = await client.consolidateLongMemory({\n  session_id: session.session_id,\n  trigger_source: \"session_end\",\n  hints: {\n    reason: \"会话结束后沉淀长期记忆\",\n  },\n});\n\nconsole.log(\"long memory queued:\", run.run_ids);\n```\n\n## 使用 AgentMemorySession 简化接入\n\n`AgentMemorySession` 会自动创建 session、写标准事件，并缓存服务端返回的 `thread_id`，后续查询和生成会自动带上线程上下文。\n\n```ts\nimport { AgentMemoryClient, AgentMemorySession } from \"@agent-dreamer/sdk\";\n\nconst client = new AgentMemoryClient({\n  baseUrl: process.env.AGENT_MEMORY_BASE_URL!,\n  apiKey: process.env.AGENT_MEMORY_API_KEY!,\n});\n\nconst agentMemory = new AgentMemorySession(client, {\n  agentInstanceId: process.env.AGENT_MEMORY_AGENT_INSTANCE_ID!,\n  externalSessionId: \"typescript-task-20260616-001\",\n  externalThreadId: \"main\",\n});\n\nawait agentMemory.recordUserMessage(\"请继续 SDK 接入任务。\");\n\nconst shortRun = await agentMemory.generateShortMemory(\"thread_end\");\nconsole.log(\"short memory queued:\", shortRun.run_ids);\n\nconst memoryContext = await agentMemory.queryContext({\n  queryText: \"继续 SDK 接入任务\",\n  queryIntent: \"execution_help\",\n  desiredMemoryTypes: [\"task_whiteboard\", \"tool_digest\", \"procedure\"],\n  limit: 6,\n  eventLimit: 3,\n});\n\nconsole.log(memoryContext.text);\n```\n\n## 查看示例\n\n```bash\ncd sdk/typescript\nnpm install\nnpm run build\nnpx tsx examples/basic.ts\nnpx tsx examples/agent_loop.ts\n```\n","readmeFilename":"README.md"}