Add complete memory module

Change-Id: Iea5dbdcf29c9ac1dd1b8d55f824f9e96e82cfb8d

Author: heimanba

.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.

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).