Tablestore:File memory

Prepare the environment

• Download the agent-memory-fuse Linux executable that matches the runtime architecture, and make the file executable.

• Enable FUSE in the Linux kernel, and grant the current user or container access to /dev/fuse.

• Install fusermount3. On some systems, the command is named fusermount.

• Create a file memory store with storageMode=filemem, and obtain the HTTPS endpoint, instance name, and all four scope fields.

• Prepare an API Key, AccessKey, or Security Token Service (STS) temporary credential. API Key authentication requires an HTTPS endpoint.

Running the tool in a container typically requires mapping /dev/fuse and granting CAP_SYS_ADMIN or equivalent user-namespace mount permissions. Use the minimum permissions required by the runtime environment.

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

Mount file memory

Run the following command. The scope matches the scope object in Quick start. Enclose the complete scope in quotation marks to prevent the shell from interpreting special characters.

./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 maintains the mount lifecycle. The following log indicates that the initial directory was loaded and mounted.

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

Keep the process running and access the mounted directory from another terminal or application process. In production, use systemd or a container orchestrator to manage the process. Do not forcibly terminate the process while the mount is in use.

The following table describes the main parameters.

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

Read and write files

After mounting, read, create, modify, rename, and delete files as you would in a regular directory.

# View files stored on the server
find /mnt/agent-memory -type f
cat /mnt/agent-memory/profile/preferences.md

# Create or update a file
mkdir -p /mnt/agent-memory/projects/alpha
printf '%s\n' '# Project decisions' '' '- Use an event-driven architecture' \
  > /mnt/agent-memory/projects/alpha/decisions.md
cat /mnt/agent-memory/projects/alpha/decisions.md

# Rename and delete a file
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 synchronized to the server during flush, fsync, or close operations. Production applications must check the return values of fsync and close. Some shell redirections do not display errors raised during close. Read critical writes back to confirm that they succeeded.

Directories are derived from file path prefixes. Directories that contain files persist across processes and remounts. Empty directories exist only in the current mount process.

Use a read-only mount

If an agent only needs to read memories, 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 a read-only file view generated from structured memories, the service automatically switches the mount to read-only. Write operations on a read-only mount return EROFS.

Rotate STS credentials

When a mount uses STS credentials, rotate the 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 so that new credentials are not exposed in command-line arguments. A successful command installs the credentials in the local mount process. Subsequent file requests verify the credentials. Only trusted processes can access the mount point and rotate credentials.

Unmount file memory

After all file operations finish and all open files are closed, run the following command.

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

After the directory is unmounted, the foreground mount process exits. If fusermount3 and fusermount are unavailable, the unmount command returns an error. Install the FUSE user-space tools before you retry.

Limitations and troubleshooting

• Only valid UTF-8 text is supported, and each file can be up to 100 KiB. Content and size violations return EILSEQ and EFBIG, respectively.

• Each scope stores up to 2,000 current files by default. Writes return ENOSPC when the quota is reached.

• When multiple clients modify the same file concurrently, stale file handles might return ESTALE. Reopen the file, read the latest content, and then decide whether to retry.

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

• Throttling or temporary service unavailability might return EAGAIN. The tool first performs bounded retries. Applications must use backoff to handle the final error.

• Symbolic links, hard links, access control lists (ACLs), application-defined extended attributes, sparse files, and cross-session file locks are not supported.

• For an operation not permitted error or failure to open /dev/fuse, check device mapping, current-user permissions, and container mount capabilities.

• For an initial directory load error, verify that the endpoint, instance name, credentials, memory store name, and scope match.

Read file metadata only

Set includeContent to False to omit content from the response. Use this option to inspect the content digest and update time.

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

Update file content

For concurrent writes, pass the most recently read contentSha256 value as expectedSha256. If another request has modified the file, the service rejects the overwrite. Read the file again before deciding whether to retry.

updated = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "content": "# User preferences\n\n- Likes latte\n- Prefers concise answers\n",
    "expectedSha256": current["contentSha256"],
})

Rename a file

UpdateItem updates content or renames a file. Each request must specify exactly one of content and newPath.

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

If the destination path exists, the request returns a conflict by default. Set "overwrite": True only when replacing the destination file is acceptable.

List files by page

ListItems returns 100 files per page by default and up to 500 files per page. If the response contains nextToken, pass it unchanged in the next request.

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"],
})

Deleting a file removes the current file. Historical versions remain available by file ID.

Redact a historical version

RedactItemVersion removes the path, content, digest, and size from a historical snapshot. The operation type, version sequence, creation time, and redaction audit information remain. Repeated requests are idempotent. Redaction does not modify the current file or create a 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, GetItemVersion still returns the version without the content field.