Add complete memory module

.changeset/complete-memory-module.md

@@ -0,0 +1,8 @@
+---
+"@openagentpack/sdk": minor
+"@openagentpack/cli": minor
+---
+
+Add a portable Memory Store and Memory lifecycle API across Qoder, Claude, and
+Volcengine Ark, including provider capability differences, CLI commands,
+declarative entry reconciliation, version history, and Ark batch creation.

.github/workflows/release.yml

@@ -33,6 +33,7 @@ jobs:
     outputs:
       channel: ${{ steps.release.outputs.channel }}
       version: ${{ steps.release.outputs.version }}
+      dist-tag: ${{ steps.release.outputs.dist-tag }}
     permissions:
       contents: read
     steps:
@@ -113,7 +114,8 @@ jobs:
       - name: Publish packages with npm Trusted Publishing
         env:
           NPM_CONFIG_PROVENANCE: "true"
-        run: bun run release:publish
+          NPM_DIST_TAG: ${{ needs.preflight.outputs.dist-tag }}
+        run: bun run release:publish -- --tag "$NPM_DIST_TAG"
 
       - name: Create immutable Git tag
         env:

README.md

@@ -145,7 +145,7 @@ Beta testers can install `@openagentpack/cli@beta`; see the [release guide](./do
 | Skill | native | native | native | native |
 | Agent | native | native | native | native |
 | MCP Server | native | native | native | native |
-| Memory Store | unsupported | native | unsupported | native |
+| Memory Store | unsupported | native | native | native |
 | Multi-Agent | unsupported | unsupported | native | native |
 | Deployment | emulated | native | native | emulated |
 | Session | native | native | native | native |

README.zh-CN.md

@@ -145,7 +145,7 @@ Beta 用户可以安装 `@openagentpack/cli@beta`；固定版本及切回稳定
 | Skill | native | native | native | native |
 | Agent | native | native | native | native |
 | MCP Server | native | native | native | native |
-| Memory Store | unsupported | native | unsupported | native |
+| Memory Store | unsupported | native | native | native |
 | Multi-Agent | unsupported | unsupported | native | native |
 | Deployment | emulated | native | native | emulated |
 | Session | native | native | native | native |

docs/examples.md

@@ -13,7 +13,7 @@ The [`examples/`](../examples) directory has runnable configs for every provider
 | Use an official MCP server | [`examples/bailian/with-mcp/`](../examples/bailian/with-mcp/) |
 | Use a vault | [`examples/bailian/with-vault/`](../examples/bailian/with-vault/) · [`examples/qoder/with-vault/`](../examples/qoder/with-vault/) |
 | Connect a credential-based IM Channel | [`examples/qoder/with-channel/`](../examples/qoder/with-channel/) |
-| Use memory stores | [`examples/qoder/with-memory/`](../examples/qoder/with-memory/) · [`examples/ark/full/`](../examples/ark/full/) |
+| Use memory stores | [`examples/qoder/with-memory/`](../examples/qoder/with-memory/) · [`examples/claude/with-memory/`](../examples/claude/with-memory/) · [`examples/ark/full/`](../examples/ark/full/) · [runtime lifecycle](../examples/memory/README.md) |
 | Upload local files (Files API) | [`examples/bailian/with-files/`](../examples/bailian/with-files/) · [`examples/ark/with-files/`](../examples/ark/with-files/) |
 | Coordinate multiple agents | [`examples/claude/multiagent/`](../examples/claude/multiagent/) · [`examples/ark/multiagent/`](../examples/ark/multiagent/) |
 | Deploy to multiple providers | [`examples/claude/multi-provider/`](../examples/claude/multi-provider/) · [`examples/qoder/multi-provider/`](../examples/qoder/multi-provider/) |
@@ -51,7 +51,7 @@ agents destroy
 | Skill | native | native | native | native |
 | Agent | native | native | native | native |
 | MCP Server | native | native | native | native |
-| Memory Store | unsupported | native | unsupported | native |
+| Memory Store | unsupported | native | native | native |
 | Multi-Agent | unsupported | unsupported | native | native |
 | Deployment | emulated | native | native | emulated |
 | Session | native | native | native | native |

docs/guides/configure-an-agent.md

@@ -128,7 +128,7 @@ agents:
 
 See [Use MCP and vaults](./use-mcp-and-vaults.md).
 
-## Memory stores (Qoder, Ark)
+## Memory stores (Qoder, Claude beta, Ark)
 
 ```yaml
 memory_stores:

docs/guides/configure-an-agent.zh-CN.md

@@ -307,7 +307,7 @@ agents:
 
 Memory Store 为 Agent 提供持久化上下文，适合存储项目知识、约定规范等长期信息。
 
-> 注意：Memory Store 目前由 Qoder 和 火山方舟 Provider 原生支持。
+> 注意：Memory Store 目前由 Qoder、Claude（beta）和火山方舟 Provider 原生支持。
 
 ```yaml
 memory_stores:

docs/guides/deploy-to-claude.md

@@ -21,9 +21,9 @@ providers:
 | Feature | Tier |
 |---------|:----:|
 | Environment, Vault, Skill, Agent, MCP Server, Multi-Agent, Deployment, Session | native |
-| Memory Store | unsupported |
+| Memory Store | native (beta) |
 
-Use a **skill** or **MCP** for context persistence where Claude has no memory store.
+Memory stores require the Claude `agent-memory-2026-07-22` beta, enabled by the adapter by default.
 
 ## Minimal agent
 

docs/reference/cli.md

@@ -123,6 +123,35 @@ Manage scheduled / triggered deployments.
 | `deployment get <name>` | Show a deployment's status and resolved bindings. |
 | `deployment run <name>` | Trigger a deployment run (native on Qoder/Claude, emulated as a session on Bailian/Volcengine Ark). |
 
+## `agents memory-store`
+
+Manage persistent stores directly. Store creation through `agents apply` remains
+the recommended declarative workflow.
+
+| Command | Description |
+|---------|-------------|
+| `create <name>` | Create a store (`--description`). |
+| `list` | List stores (`--limit`, `--cursor`, `--include-archived`). |
+| `get <store-id>` | Retrieve a store. |
+| `update <store-id>` | Update `--name` and/or `--description`. |
+| `archive <store-id>` | Archive a store (Qoder/Claude). |
+| `delete <store-id>` | Permanently delete a store and its memories. |
+
+## `agents memory`
+
+Manage individual text memories. Content can be passed with `--content` or
+`--content-file`. Portable paths are relative; adapters handle wire-format differences.
+
+| Command | Description |
+|---------|-------------|
+| `create <store-id> <path>` | Create one memory. |
+| `batch-create <store-id> <json-file>` | Ark batch create; supports `--on-conflict overwrite\|fail`. |
+| `list <store-id>` | List memories; supports pagination, prefix/depth and `--full`. |
+| `get <store-id> <memory-id>` | Retrieve full content. |
+| `update <store-id> <memory-id>` | Update content/path; `--expected-sha256` enables optimistic concurrency where supported. |
+| `delete <store-id> <memory-id>` | Delete one memory. |
+| `version list|get|redact` | Immutable history operations (Qoder/Claude). |
+
 ## `agents models`
 
 | Subcommand | Description |

docs/reference/configuration.md

@@ -197,10 +197,15 @@ memory_stores:
   <name>:
     description: <string>
     provider: <string>          # optional
+	metadata: { <string>: <string> } # optional
     entries: [ { key: <string>, content: <string> } ]
 ```
 
-Supported on **Qoder** and **Volcengine Ark** (**Bailian** and **Claude**: `unsupported`).
+Supported on **Qoder**, **Claude (beta)**, and **Volcengine Ark** (**Bailian**: `unsupported`).
+
+Declarative `entries` are managed seeds: apply creates or updates those paths but
+preserves additional memories written by agents. Runtime CRUD and version commands
+are documented in [`examples/memory/`](../../examples/memory/README.md).
 
 ## Skill
 

docs/reference/providers.md

@@ -13,7 +13,7 @@ OpenAgentPack targets multiple agent platforms behind one declarative config. Ea
 | Skill | native | native | native | native | Claude uploads via `files[]`; the other providers upload zip archives. Volcengine Ark is create + attach only. |
 | Agent | native | native | native | native | Core managed-agent resource. |
 | MCP Server | native | native | native | native | Bailian uses official managed servers referenced by name. |
-| Memory Store | unsupported | native | unsupported | native | Qoder and Ark are implemented. Claude's upstream API now has Memory Stores, but its OpenAgentPack adapter does not yet. |
+| Memory Store | unsupported | native | native | native | Qoder, Claude (beta), and Ark adapters implement the complete upstream lifecycle. |
 | Multi-Agent | unsupported | unsupported | native | native | Coordinator topology is available on Claude and Volcengine Ark. |
 | Deployment | emulated | native | native | emulated | Qoder and Claude use native deployments; Bailian and Ark expand a deployment into a session at `run` time. |
 | Session | native | native | native | native | Runtime sessions are native on every provider. |
@@ -63,7 +63,7 @@ Last reviewed: **2026-07-17**. The evidence labels below deliberately separate u
 | Skills | Built-in Anthropic skills plus custom zip or individual-file uploads; max 20 per session | CRUD/list/get/download implemented; adapter uploads `files[]` | Official documentation currently lists create and get only | Create/get/attach implemented; update recreates; list/delete are unavailable upstream |
 | Multi-agent | Coordinator delegates to persistent, context-isolated threads sharing sandbox/files/vaults | Coordinator topology implemented | Agent schema includes `multiagent`; Session APIs expose thread list/detail/events/stream | Coordinator topology implemented; thread inspection is not exposed through `ProviderAdapter` |
 | Deployment | Native scheduled deployments with cron/timezone and run history | Native lifecycle and run implemented | The official Managed Agents API catalog contains no Deployment resource | Emulated locally and expanded into a Session at run time |
-| Memory Store | Official API supports persistent, versioned memories mounted read-only or read-write; up to 8 stores per session | **Gap:** not implemented, so capability remains `unsupported` in OpenAgentPack | Official CRUD for stores plus create/batch-create/list/get/update/delete for memories | Store create/delete and Session binding implemented; list/get/update and memory-content operations are adapter gaps |
+| Memory Store | Store CRUD/archive, memory CRUD, optimistic concurrency, immutable versions and redaction are implemented; paths are normalized from Claude's absolute form | Store CRUD, memory CRUD, Session binding, versions and redaction are implemented behind `agent-memory-2026-07-22` | Store CRUD plus memory create/batch-create/list/get/update/delete are implemented | Full upstream surface is implemented; Ark is last-write-wins and does not expose version APIs |
 
 Primary references: [Claude API overview](https://platform.claude.com/docs/en/api/overview), [Claude Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview), [sessions and event streaming](https://platform.claude.com/docs/en/managed-agents/events-and-streaming), [skills](https://platform.claude.com/docs/en/managed-agents/skills), [multi-agent sessions](https://platform.claude.com/docs/en/managed-agents/multi-agent), [scheduled deployments](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments), [memory stores](https://platform.claude.com/docs/en/managed-agents/memory), and the [Volcengine Ark Managed Agents API reference](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2555910?lang=zh).
 

docs/reference/providers.zh-CN.md

@@ -32,7 +32,7 @@ OpenAgentPack 通过 Provider 适配器与不同的 AI Agent 平台交互。每
 | Skill | native | native | native | native | Claude 使用 files[]；其余 Provider 上传 zip |
 | Agent | native | native | native | native | 核心资源 |
 | MCP Server | native | native | native | native | 通过 Agent 的 MCP 配置挂载 |
-| Memory Store | unsupported | native | unsupported | native | Qoder、方舟已接入；Claude 上游已有 Memory Store，但 OpenAgentPack Adapter 尚未实现 |
+| Memory Store | unsupported | native | native | native | Qoder、Claude（beta）、方舟均已接入 |
 | Multi-Agent | unsupported | unsupported | native | native | Claude 与 火山方舟 支持 coordinator |
 | Deployment | emulated | native | native | emulated | Qoder 和 Claude 使用原生 Deployment；百炼和火山方舟在 `run` 时展开为 Session |
 | Session | native | native | native | native | 四者均原生支持 |
@@ -76,7 +76,7 @@ OpenAgentPack 通过 Provider 适配器与不同的 AI Agent 平台交互。每
 | Skill | 支持 Anthropic 内置 Skill 与自定义 zip/多文件上传；每 Session 最多 20 个 | 已实现 CRUD、枚举、查询和下载；Adapter 使用 `files[]` 上传 | 官方文档当前仅列出创建和查询详情 | 已实现创建、查询和挂载；更新通过重建模拟；枚举、删除是上游缺失 |
 | Multi-Agent | Coordinator 可调度持久、上下文隔离的线程；共享沙箱、文件和 Vault | 已实现 Coordinator 拓扑 | Agent Schema 含 `multiagent`；Session API 提供 Thread 列表、详情、事件查询和流式读取 | 已实现 Coordinator 拓扑；`ProviderAdapter` 尚未暴露 Thread 查询 |
 | Deployment | 原生定时 Deployment，支持 cron、时区和运行历史 | 已实现原生生命周期和运行 | 官方 Managed Agents API 目录中没有 Deployment 资源 | 本地模拟，运行时展开为 Session |
-| Memory Store | 官方 API 支持跨 Session 持久化、版本化记忆，可只读/读写挂载；每 Session 最多 8 个 | **能力缺口：尚未接入**，因此 OpenAgentPack 中仍为 `unsupported` | 官方提供记忆库 CRUD，以及记忆创建、批量创建、枚举、查询、更新、删除 | 已实现记忆库创建、删除和 Session 挂载；枚举、查询、更新及记忆内容操作尚未接入 |
+| Memory Store | 已实现 Store CRUD/归档、Memory CRUD、乐观并发、版本查询与 redact；统一层会转换 Claude 的绝对路径 | 已通过 `agent-memory-2026-07-22` 接入 Store CRUD、Memory CRUD、Session 挂载、版本与 redact | 官方提供记忆库 CRUD，以及记忆创建、批量创建、枚举、查询、更新、删除 | 已完整接入上游能力；方舟采用 last-write-wins，且当前不暴露版本接口 |
 
 主要依据：[Claude API 总览](https://platform.claude.com/docs/en/api/overview)、[Claude Managed Agents 总览](https://platform.claude.com/docs/en/managed-agents/overview)、[Session Event Stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming)、[Skills](https://platform.claude.com/docs/en/managed-agents/skills)、[Multi-Agent](https://platform.claude.com/docs/en/managed-agents/multi-agent)、[Scheduled Deployments](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments)、[Memory Stores](https://platform.claude.com/docs/en/managed-agents/memory)，以及[火山方舟 Managed Agents API 参考](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2555910?lang=zh)。
 
@@ -112,7 +112,7 @@ OpenAgentPack 通过 Provider 适配器与不同的 AI Agent 平台交互。每
 | Agent | full | full | 待验证 | existence | 火山方舟 当前执行存在性检查 |
 | Skill | existence | existence | existence | existence | 可发现缺失/删除，不比较包内容 |
 | Vault | existence | existence | existence | existence | 凭证内容通常不可读回，不比较内容 |
-| Memory Store | unsupported | existence | unsupported | existence | 可发现资源缺失 |
+| Memory Store | unsupported | existence | existence | existence | 可发现资源缺失 |
 | Deployment | unsupported | native | native 路径待验证 | unsupported | 百炼和火山方舟的 emulated Deployment 为本地记录 |
 
 Claude 的 drift detection 接口路径已预留；本仓库中的 live baseline 因 Anthropic API 账号余额不足未完成 Agent 创建验证。
@@ -128,9 +128,9 @@ Claude 的 drift detection 接口路径已预留；本仓库中的 live baseline
 示例诊断输出：
 
 ```
-claude.memory_store.unsupported:
-  Claude exposes Memory Stores, but the OpenAgentPack adapter has not implemented them yet.
-  use skill knowledge or MCP until Claude Memory Store support is added to the adapter
+bailian.memory_store.unsupported:
+  no memory store primitive on Bailian
+  use skill knowledge or MCP for persistent context
 
 qoder.multiagent.unsupported:
   no multiagent primitive on Qoder.

examples/README.md

@@ -20,6 +20,7 @@ examples/
 │   ├── basic/                   minimal agent
 │   ├── with-skills/             skill + file-referenced instructions
 │   ├── with-mcp/                MCP server + vault + restricted network
+│   ├── with-memory/             persistent memory store (beta)
 │   ├── multiagent/              coordinator multi-agent (Claude only)
 │   ├── multi-provider/          same agent on both Claude + Qoder
 │   ├── deployment/              schedule + outcome rubric (native)
@@ -28,7 +29,7 @@ examples/
 │   ├── basic/                   minimal agent
 │   ├── with-skills/             skill + file-referenced instructions
 │   ├── with-mcp/                MCP server + vault + restricted network
-│   ├── with-memory/             memory_store (Qoder only)
+│   ├── with-memory/             persistent memory store
 │   ├── with-vault/              vault only
 │   ├── vault-only/              vault-only project
 │   ├── multi-provider/          same agent on both Claude + Qoder
@@ -48,6 +49,9 @@ examples/
     └── run-session-complex.ts   tool calls + streaming events
 ```
 
+See [`memory/README.md`](./memory/README.md) for portable Memory CRUD, provider
+extensions, and live-test commands.
+
 ## Provider capability matrix
 
 | Feature | Bailian | Qoder | Claude | Volcengine Ark | Notes |
@@ -57,7 +61,7 @@ examples/
 | Skill | native | native | native | native | Claude uploads via `files[]`; others upload zip; Volcengine Ark is create + attach only. |
 | Agent | native | native | native | native | Core managed-agent resource. |
 | MCP Server | native | native | native | native | Bailian uses official managed servers referenced by name. |
-| Memory Store | unsupported | native | unsupported | native | Qoder and Volcengine Ark. |
+| Memory Store | unsupported | native | native | native | Qoder, Claude (beta), and Volcengine Ark. |
 | Multi-Agent | unsupported | unsupported | native | native | Claude and Volcengine Ark support coordinator. |
 | Deployment | emulated | native | native | emulated | Qoder and Claude schedule server-side; Bailian and Ark expand into a session at `run` time. |
 | Session | native | native | native | native | All four support runtime sessions. |

examples/ark/full/agents.yaml

@@ -52,11 +52,16 @@ skills:
     source: ./skills/summarize/
     description: "Produce concise summaries"
 
-# Ark supports native memory stores (Claude does not). A memory store persists
-# context across sessions.
+# Ark supports native memory stores. It also offers partial-success batch memory
+# creation, while updates use last-write-wins and version history is not exposed.
 memory_stores:
   project-notes:
     description: "Shared long-lived project notes"
+    metadata:
+      example: ark-full
+    entries:
+      - key: project/overview.md
+        content: "This store holds durable project context shared across sessions."
 
 agents:
   researcher:

examples/claude/with-memory/agents.yaml

@@ -0,0 +1,37 @@
+version: "1"
+
+providers:
+  claude:
+    api_key: ${ANTHROPIC_API_KEY}
+
+defaults:
+  provider: claude
+
+environments:
+  dev:
+    config:
+      type: cloud
+      networking:
+        type: unrestricted
+
+memory_stores:
+  project-memory:
+    description: "Long-lived project decisions and coding conventions"
+    metadata:
+      example: with-memory
+    entries:
+      - key: decisions/architecture.md
+        content: "Start with a modular monolith and record extraction triggers here."
+      - key: conventions/testing.md
+        content: "Public behavior requires integration coverage."
+
+agents:
+  assistant:
+    description: "Project assistant with persistent memory"
+    model: claude-sonnet-4-6
+    instructions: "Read project memory before making architectural recommendations."
+    environment: dev
+    tools:
+      builtin: [bash, text_editor]
+    memory_stores: [project-memory]
+