# MemoryAsset ACL Strategy: How Fixed Binding + ACL Controls Agent Loadouts in TencentDB Agent Memory

> Learn how the MemoryAsset ACL Strategy uses Fixed Binding and ACLs to control agent loadouts in TencentDB Agent Memory, ensuring secure access to memory assets.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-31

---

**The MemoryAsset ACL Strategy combines Fixed Binding and ACL layers to restrict which memory assets an Agent can access, first limiting Agents to pre-selected loadouts then enforcing fine-grained Team → User → Agent → Visibility permissions.**

This two-stage permission system is central to the TencentDB Agent Memory architecture. It allows teams to share institutional knowledge through shared memory assets while maintaining strict data isolation. According to the repository's README, "assets are uniformly registered as Memory Assets" and the hub "uses Fixed Binding + ACL to determine which assets a given Agent can use"【README.md#L57-L60】.

## How Fixed Binding Creates Agent Loadouts

**Fixed Binding** is the first filtering layer. When an Agent is created or edited, administrators explicitly bind specific memory assets to that Agent's configuration. This creates an immutable **loadout** that defines exactly which Chat Memory, Skills, Wiki, and CodeGraph assets the Agent may attempt to access.

Assets outside this bound set are invisible to the Agent regardless of ACL permissions. This architectural decision prevents accidental data exposure and simplifies runtime permission evaluation.

### Creating an Agent with a Fixed Loadout

```typescript
import { MemoryCoreClient } from '@tencentdb/memory-core';

const client = new MemoryCoreClient({ endpoint, apiKey });

await client.createAgent({
  name: 'Research Scout',
  team_id: 'team-123',
  loadout: {
    chat_memory_ids: ['cm-987'],
    wiki_ids:        ['wiki-321'],
    skill_ids:       ['skill-654'],
  },
});

```

The `loadout` object in the `createAgent` call establishes the fixed binding. The Agent cannot access assets beyond these IDs, even if permissions would otherwise allow it【README.md#L11-L13】.

## ACL Layer: Team → User → Agent → Visibility Enforcement

After Fixed Binding narrows the asset pool, the **ACL (Access Control List)** subsystem applies granular permissions. The ACL system stores `meta_asset_acl` records in the metadata database that grant or deny specific actions to identified subjects.

### Core ACL Data Model

In [`MemoryCore/src/metadata/store/sqlite-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/store/sqlite-adapter.ts), the ACL table schema defines the permission structure:

```typescript
// From sqlite-adapter.ts#L263-L289
CREATE TABLE meta_asset_acl (
  id TEXT PRIMARY KEY,
  asset_id TEXT NOT NULL,
  subject_type TEXT NOT NULL,  -- 'user', 'team_role', 'agent'
  subject_id TEXT NOT NULL,
  permission TEXT NOT NULL,    -- 'read', 'write', 'admin'
  effect TEXT NOT NULL,        -- 'allow' or 'deny'
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

```

This schema supports three subject types with hierarchical evaluation:
- `user` — individual user accounts
- `team_role` — role-based group permissions
- `agent` — Agent-specific overrides

### Permission Checker Implementation

The runtime ACL evaluation occurs in [`MemoryCore/src/metadata/service/permission-checker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/service/permission-checker.ts). The core logic iterates matching ACL records and applies precedence rules:

```typescript
// From permission-checker.ts#L27-L33 and #L86-L94
export async function checkPermission(request: AclCheckRequest): Promise<boolean> {
  const aclRecords = await fetchAclRecords({
    asset_id: request.asset_id,
    subject_types: ['agent', 'user', 'team_role'], // Evaluation order
  });

  for (const record of aclRecords) {
    if (matchesSubject(record, request) && record.permission === request.action) {
      return record.effect === 'allow';
    }
  }
  return false; // Default deny
}

```

The iteration order prioritizes `agent`-specific rules, then `user`, then `team_role`, allowing fine-grained overrides of broader permissions【permission-checker.ts#L27-L33】【permission-checker.ts#L86-L94】.

### Granting ACL Permissions

Administrators grant access through the API defined in [`MemoryCore/src/metadata/router/v3-meta-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/router/v3-meta-router.ts):

```typescript
// Grant read access to a specific user
await client.grantAcl({
  asset_id:     'wiki-321',
  subject_type: 'user',
  subject_id:   'user-42',
  permission:   'read',
  effect:       'allow',
});

```

The `aclGrantSchema` validates requests with these exact fields【v3-meta-router.ts#L319-L325】.

### Runtime ACL Check Flow

When an Agent attempts asset access, [`MemoryProxy/src/tdai/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/client.ts) performs the verification:

```typescript
// From client.ts#L329-L361
const aclResponse = await fetch(`${base}/v3/meta/acl/check`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id:   context.userId,
    asset_id:  requestedAssetId,
    action:    'read',
    agent_id:  context.agentId,  // Enables agent-specific ACL evaluation
  }),
});

const { allowed } = await aclResponse.json();
if (!allowed) {
  throw new PermissionDeniedError(`ACL denied for ${requestedAssetId}`);
}

```

The `agent_id` parameter enables the permission checker to apply Agent-specific overrides to inherited User or Team Role permissions【client.ts#L329-L361】.

## Asset Visibility Levels

Assets carry a visibility field that interacts with ACL evaluation:

| Visibility | Behavior |
|------------|----------|
| `private` | Only explicit ACL grants permit access |
| `team` | Team members gain read access by default; ACL can restrict |
| `restricted` | Requires explicit ACL grant regardless of team membership |

The visibility field is defined in [`MemoryCore/src/metadata/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/types.ts) and evaluated during the ACL check alongside explicit permission records.

## Debugging ACL Configuration

List all ACL entries for an asset to diagnose permission issues:

```typescript
// List ACL entries via /v3/meta/acl/list
const aclList = await client.listAcl({ asset_id: 'wiki-321' });

// Returns array of: { asset_id, subject_type, subject_id, permission, effect }
console.table(aclList);

```

The list endpoint is defined at `v3-meta-router.ts#L444-L447`【v3-meta-router.ts#L444-L447】.

## Key Implementation Files

| File Path | Responsibility |
|-----------|---------------|
| [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) | Conceptual documentation of Fixed Binding + ACL strategy【README.md】 |
| [`MemoryCore/src/metadata/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/types.ts) | Asset metadata and ACL type definitions【types.ts】 |
| [`MemoryCore/src/metadata/store/sqlite-adapter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/store/sqlite-adapter.ts) | ACL persistence layer with `meta_asset_acl` table【sqlite-adapter.ts#L263-L289】 |
| [`MemoryCore/src/metadata/service/permission-checker.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/service/permission-checker.ts) | Core ACL evaluation logic【permission-checker.ts】 |
| [`MemoryCore/src/metadata/router/v3-meta-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/router/v3-meta-router.ts) | REST API for `aclGrant`, `aclRevoke`, `aclList`, `aclCheck`【v3-meta-router.ts】 |
| [`MemoryProxy/src/tdai/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/client.ts) | Proxy-side ACL enforcement before asset retrieval【client.ts#L329-L361】 |
| [`MemoryPanel/web/src/services/asset-scope-store.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/services/asset-scope-store.ts) | UI state management for fixed binding configuration【asset-scope-store.ts】 |

## Summary

- **Fixed Binding** creates immutable Agent loadouts that limit which memory assets an Agent can discover.
- **ACL** applies fine-grained permissions within the bound set, evaluating `agent`, `user`, and `team_role` subject types in that precedence order.
- The **two-layer model** enables teams to share experience assets while maintaining strict data isolation through `private`, `team`, and `restricted` visibility levels.
- **Default deny** applies when no ACL records match, ensuring no accidental access grants.
- Runtime enforcement occurs in `MemoryProxy` before asset retrieval, with the permission checker in `MemoryCore` serving as the authoritative decision engine.

## Frequently Asked Questions

### How does Fixed Binding differ from ACL in the MemoryAsset security model?

Fixed Binding operates at configuration time, permanently attaching specific asset IDs to an Agent's loadout. ACL operates at request time, evaluating whether the requesting context (Team → User → Agent) has permission to perform the requested action on an asset within that loadout. Fixed Binding is a coarse gate; ACL provides fine-grained control.

### Can an Agent access assets not in its Fixed Binding if ACL permissions exist?

No. Fixed Binding is evaluated before ACL checks. Assets outside the bound loadout are completely invisible to the Agent regardless of ACL configuration. This prevents information leakage through enumeration attacks and simplifies security auditing.

### What happens when multiple ACL records conflict for the same subject?

The permission checker evaluates records in `agent`, `user`, `team_role` order and returns on the first match. More specific subject types override broader ones. An `agent` record takes precedence over a `user` record, which takes precedence over a `team_role` record【permission-checker.ts#L27-L33】.

### How do I troubleshoot "ACL denied" errors in production?

Use the `/v3/meta/acl/list` endpoint to retrieve all ACL records for the target asset. Verify that: (1) the asset ID exists in the Agent's loadout, (2) at least one record matches the requesting `user_id` or `agent_id` with `effect: 'allow'`, and (3) no more specific record with `effect: 'deny'` exists higher in the evaluation order【v3-meta-router.ts#L444-L447】.