Tablestore:File memory

1. Create a memory store

Create a memory store that outputs both structured memory and files:

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="your-api-key",
    ots_endpoint="https://your-instance.cn-beijing.ots.aliyuncs.com",
    ots_instance_name="your-instance-name",
)

client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Agent 对话记忆",
    "inputType": "messages",
    "outputTypes": ["structured", "file"],
})

2. Write conversations

Write conversation messages to the memory store. The service generates read-only files asynchronously.

resp = client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "shopping-app",
        "tenantId": "user-001",
        "agentId": "shopping-assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "我平时喝美式咖啡，不加糖。"},
        {"role": "assistant", "content": "好的，我会记住你的饮品偏好。"},
    ],
    "sync": False,
})
request_id = resp["requestId"]

3. Wait for file generation to complete

Query the generation task status to confirm that the service has generated the read-only files.

task = client.get_memory_task({
    "memoryStoreName": "agent_memory",
    "requestId": request_id,
})
print(task["task"]["status"])

When task.status is completed, all configured outputs have been generated. For dual-output memory stores, the overall task is completed only after both structured memory and files have been generated.

4. List and read files

Use the exact four-level scope from the write operation to browse the service-generated read-only files. Service-generated files do not support wildcard scopes.

scope = {
    "appId": "shopping-app",
    "tenantId": "user-001",
    "agentId": "shopping-assistant",
    "runId": "session-001",
}

page = client.list_items({
    "type": "memoryfile",
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "limit": 20,
})

# Get the actual path from items, then read the content
for entry in page["items"]:
    item = client.get_item({
        "type": "memoryfile",
        "memoryStoreName": "agent_memory",
        "scope": scope,
        "path": entry["path"],
        "view": "full",
    })
    print(item["path"], item["content"])

Calling create, update, rename, or delete interfaces on these files returns 409 READ_ONLY_STORE. To modify content, continue writing conversations or maintain the source memory through structured memory interfaces.

Prepare the environment

• Obtain the agent-memory-fuse Linux executable that matches your runtime architecture, and add execute permissions.

• FUSE is enabled in the Linux kernel, and the current user or container can access /dev/fuse.

• fusermount3 is installed. On some systems, the command name is fusermount.

• A file memory store with storageMode=filemem has been created. Prepare the instance HTTPS endpoint, instance name, and complete four-level scope.

• An API Key, AccessKey, or STS temporary credential is ready. API Keys must be used with HTTPS endpoints.

Running in a container typically requires mapping /dev/fuse and granting CAP_SYS_ADMIN or equivalent user namespace mount permissions. Use least-privilege configuration based on your runtime environment.

chmod +x ./agent-memory-fuse
mkdir -p /mnt/agent-memory

Mount file memory

Run the following command. The scope in the example corresponds to the scope object in the quick start. Use quotes to wrap the complete scope to prevent the shell from interpreting special characters unexpectedly.

./agent-memory-fuse mount \
  --endpoint https://your-instance.cn-beijing.ots.aliyuncs.com \
  --instance your-instance-name \
  --credential apikey:your-api-key \
  --store agent_files \
  --scope 'app-001#user-001#assistant#session-001' \
  --session fuse-session-001 \
  /mnt/agent-memory

The mount command runs in the foreground and manages the mount lifecycle. The following log indicates that the initial directory load and mount succeeded.

mounted /mnt/agent-memory: store=agent_files files=1 readOnly=false

Keep this process running and access the mount directory from another terminal or business process. In production, use systemd or a container orchestration system to manage the process. Do not forcefully terminate the process while the mount is still in use.

The main parameters are as follows.

--credential contains sensitive information. The example only shows the parameter format. Do not write real credentials into code, images, logs, or shared scripts. Prefer short-lived credentials with restricted permissions.

Read and write files

After the mount succeeds, you can read, create, modify, rename, and delete files as you would in a regular directory.

# View existing server-side files
find /mnt/agent-memory -type f
cat /mnt/agent-memory/profile/preferences.md

# Create or update files
mkdir -p /mnt/agent-memory/projects/alpha
printf '%s\n' '# 项目决策' '' '- 使用事件驱动架构' \
  > /mnt/agent-memory/projects/alpha/decisions.md
cat /mnt/agent-memory/projects/alpha/decisions.md

# Rename and delete files
mv /mnt/agent-memory/projects/alpha/decisions.md \
  /mnt/agent-memory/projects/alpha/architecture.md
rm /mnt/agent-memory/projects/alpha/architecture.md

Files are synced to the server on flush, fsync, or close. Production applications must check the return values of fsync and close. Some shell redirections do not surface errors during the close stage. For important writes, re-read the file after completion to confirm.

Directories are formed from file path prefixes. Directories that contain files can be restored across processes and remounts. Empty directories exist only within the current mount process.

Read-only mount

If the agent only needs to read memory, add --read-only before the mount directory argument.

./agent-memory-fuse mount \
  --endpoint https://your-instance.cn-beijing.ots.aliyuncs.com \
  --instance your-instance-name \
  --credential apikey:your-api-key \
  --store agent_files \
  --scope 'app-001#user-001#assistant#session-001' \
  --session fuse-reader-001 \
  --read-only \
  /mnt/agent-memory

For read-only file views generated from structured memory, the server automatically switches the mount to read-only. Write operations on a read-only mount return EROFS.

Rotate STS credentials

When mounting with STS credentials, you can rotate the complete AccessKey ID, AccessKey Secret, and STS Token without unmounting the directory. The credential provider must write the following JSON to standard output and pipe it to the rotation command.

{"accessKeyId":"new-access-key-id","accessKeySecret":"new-access-key-secret","stsToken":"new-sts-token"}

your-credential-provider | \
  ./agent-memory-fuse rotate-credential --mountpoint /mnt/agent-memory

The rotation command reads credentials from standard input to avoid putting new credentials in command-line arguments. A successful command indicates that the new credentials have been installed in the local mount process. Whether the credentials are valid will be confirmed in subsequent file requests. Only trusted processes can access the mount point and perform credential rotation.

Unmount file memory

After completing file operations and closing all open files, run the following command.

./agent-memory-fuse umount /mnt/agent-memory

After unmounting succeeds, the foreground mount process exits. If the system lacks both fusermount3 and fusermount, the unmount command returns an error. Install FUSE userspace tools first.

Limits and troubleshooting

• Only valid UTF-8 text is supported. The maximum size of a single file is 100 KiB. Exceeding these limits returns EILSEQ or EFBIG, respectively.

• Each scope supports a maximum of 2,000 current files by default. When the quota is reached, writes return ENOSPC.

• When multiple clients concurrently modify the same file, stale file handles may return ESTALE. Reopen and read the latest content before deciding whether to retry.

• Invalid credentials or an expired STS Token return EACCES. Rotate credentials or remount with valid credentials.

• Service rate limiting or brief unavailability may return EAGAIN. The tool performs bounded retries first. Applications should still use backoff strategies to handle final errors.

• Symbolic links, hard links, ACLs, extended attributes, sparse files, and cross-session file locks are not supported.

• If you see operation not permitted or cannot open /dev/fuse, check device mapping, current user permissions, and container mount capabilities.

• If you see an initial directory load error, check whether the endpoint, instance name, credentials, memory store name, and scope match.

Read metadata only

current = client.get_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "includeContent": False,
})
print(current["contentSha256"], current["updatedAt"])

Update file content

updated = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "content": "# 用户偏好\n\n- 喜欢拿铁\n- 偏好简洁回答\n",
    "expectedSha256": current["contentSha256"],
})

Rename a file

renamed = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "newPath": "/profile/user-preferences.md",
    "expectedSha256": updated["contentSha256"],
})

List files with pagination

next_token = None
while True:
    request = {
        "memoryStoreName": "agent_files",
        "scope": scope,
        "pathPrefix": "/profile/",
        "limit": 100,
    }
    if next_token:
        request["nextToken"] = next_token

    page = client.list_items(request)
    for entry in page["items"]:
        print(entry["path"])

    next_token = page.get("nextToken")
    if not next_token:
        break

Delete a file

client.delete_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/user-preferences.md",
    "expectedSha256": renamed["contentSha256"],
})

Redact historical versions

RedactItemVersion clears the path, content, content hash, and size of a historical snapshot. It preserves the operation type, version sequence, creation time, and redaction audit information. Repeat requests are idempotent. Redaction does not modify the current file or create a new version.

redacted = client.redact_item_version({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "itemId": version["itemId"],
    "versionId": version["versionId"],
    "versionSeq": version["versionSeq"],
    "sessionId": "privacy-job-001",
})
print(redacted["redacted"], redacted["redactedAt"])

After redaction, calling GetItemVersion still returns the version, but it no longer includes content.