Add complete memory module (#43)

* Add complete memory module

Change-Id: Iea5dbdcf29c9ac1dd1b8d55f824f9e96e82cfb8d

* Fix beta npm dist-tag

Change-Id: I5e3e201d94cdbe7a239f23a7dbd4d8fd89726b80

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.

.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