# Understanding Visibility Semantics for Memory Assets in TencentDB Agent Memory

> Explore five visibility semantics private team restricted agent and task for memory assets in TencentDB Agent Memory Learn how these levels control access across layers and maximize security

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-08-21

---

**Memory assets in TencentDB Agent Memory support five distinct visibility levels—`private`, `team`, `restricted`, `agent`, and `task`—that determine which users, agents, or tasks can access an asset, enforced across both control-plane metadata and data-plane proxy layers.**

The **TencentDB-Agent-Memory** platform uses a granular **visibility** attribute to govern access to memory assets stored within teams. Defined by the `AssetVisibility` type in the core SDK, this attribute works in conjunction with the ACL system to determine whether an asset remains personal, shared across a team, or bound to specific execution contexts.

## The Five Visibility Levels

The `AssetVisibility` type accepts one of five string literals, each representing a distinct access boundary. These are defined in [`sdk/memory-core/typescript/src/v3/metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/metadata-types.ts):

```typescript
export type AssetVisibility = "private" | "team" | "restricted" | "agent" | "task";

```

### Private

**`private`** assets are visible **only to their owner**—the user who created the asset. No other team members can discover or access the asset through standard queries unless an explicit ACL grant is added. This level is ideal for personal skill libraries, draft prompts, or experimental tools that the owner is not yet ready to share.

### Team

**`team`** visibility shares the asset with **every member of the team**. All teammates can read the asset (subject to ACL rules) and, if they hold appropriate permissions, can bind it to their agents. Use this for team-wide skill pools, shared code-graph resources, or communal wiki pages that serve as canonical knowledge bases.

### Restricted

**`restricted`** assets remain **hidden by default** and require an explicit **ACL grant** (`allow`) for access. This offers tighter control than `team` visibility while maintaining shareability. Adopt this level for sensitive assets like confidential models, regulated knowledge bases, or pre-release skills that should only reach a subset of teammates.

### Agent

**`agent`** visibility binds an asset to a **specific agent**, making it visible only to that agent and its owner. This supports **fixed-asset bindings** where an asset must remain within a single agent's context. Typical use cases include agent-specific prompts, personal tools, or custom LLM extensions that should not leak across agent boundaries.

### Task

**`task`** visibility scopes an asset to a **specific task**, limiting visibility to participants (agents and users) involved in that active task. This is designed for temporary assets like one-off skills, task-specific knowledge graphs, or ephemeral data created for short-lived projects that should disappear from view once the task concludes.

## Architecture: Two-Layer Enforcement

The platform enforces visibility semantics through two complementary architectural layers.

### Control-Plane Metadata

The **metadata service** stores the `visibility` field within `AssetEntity` objects. When you create or update an asset, this value persists in the metadata store as defined in [`MemoryCore/src/metadata/store/metadata-store.contract.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/store/metadata-store.contract.ts). The control plane validates that all subsequent access requests respect this baseline visibility before evaluating granular ACL rules.

### Data-Plane Filtering

The **proxy and panel layers** apply a **visibility whitelist** when listing assets. In [`MemoryProxy/src/meta/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/meta/client.ts), the server explicitly passes visibility filters (e.g., `visibility: 'team'`) to retrieve only team-shared assets. Similarly, the UI logic in [`MemoryPanel/web/src/pages/skills/SkillsPage/components/useSkillsPanel.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/skills/SkillsPage/components/useSkillsPanel.ts) filters the `visibility` field when rendering tabs like "Team Assets," ensuring users only see assets matching their current context.

## Implementing Visibility in Practice

### Creating Assets with Specific Visibility

When creating assets via the TypeScript SDK, specify the `visibility` property in the `CreateAssetRequest` payload:

```typescript
import { CreateAssetRequest } from '@tencentcloud/memory-core';

// Personal skill hidden from teammates
const privateSkill: CreateAssetRequest = {
  asset_id: 'skill-001',
  team_id: 'team-123',
  asset_type: 'skill',
  name: 'My Secret Skill',
  owner_user_id: 'user-abc',
  source_type: 'manual',
  visibility: 'private',
};

// Shared team resource
const teamWiki: CreateAssetRequest = {
  asset_id: 'wiki-007',
  team_id: 'team-123',
  asset_type: 'llm_wiki',
  name: 'Team Handbook',
  owner_user_id: 'user-abc',
  source_type: 'git',
  visibility: 'team',
};

```

### Querying by Visibility

Client-side APIs in [`MemoryPanel/web/src/lib/api/assets.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/lib/api/assets.ts) accept `visibility` as a query parameter to filter results:

```typescript
import { assetsApi } from '@/lib/api/assets';

// Retrieve only team-shared assets
const teamAssets = await assetsApi.list({
  team_id: 'team-123',
  visibility: ['team'],
});

```

### Overriding Restricted Visibility with ACL

For `restricted` assets, grant access through explicit ACL entries:

```typescript
import { grantAclApi } from '@/lib/api/assets';

await grantAclApi({
  asset_id: 'skill-xyz',
  subject_type: 'user',
  subject_id: 'user-123',
  permission: 'read',
  effect: 'allow',
  granted_by: 'user-abc',
});

```

To fetch assets visible within a specific task context, use the metadata service with visibility filters enabled:

```typescript
import { listWithDetail } from '@/MemoryCore/src/metadata/service/metadata-service';

const taskAssets = await listWithDetail({
  agent_id: 'agent-777',
  apply_visibility_filter: true,
  touch_usage: false,
});

```

## Summary

- **TencentDB Agent Memory** defines five visibility levels (`private`, `team`, `restricted`, `agent`, `task`) to control asset discovery and access.
- The `AssetVisibility` type is declared in [`sdk/memory-core/typescript/src/v3/metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/metadata-types.ts) and stored within `AssetEntity` metadata.
- **Private** assets restrict access to the owner, while **team** assets are discoverable by all teammates.
- **Restricted** assets require explicit ACL grants, sitting between private and team visibility in terms of openness.
- **Agent** and **task** visibility bind assets to specific runtime contexts, preventing leakage across agent boundaries or task lifecycles.
- Enforcement occurs in both the metadata service (control-plane) and the proxy/panel layers (data-plane) through whitelist filtering.

## Frequently Asked Questions

### What is the difference between team and restricted visibility?

**`team`** visibility automatically exposes assets to all team members, whereas **`restricted`** assets remain invisible until the owner explicitly grants access via an ACL entry. Use `team` for general collaboration and `restricted` when you need to audit or limit exactly which users can access sensitive resources.

### How does task visibility handle asset lifecycle?

Assets marked with **`task`** visibility are only accessible to participants of the specific task while it remains active. Once the task completes or the participant is removed, the asset becomes inaccessible through standard queries, though it persists in storage until explicitly deleted by the owner or an administrator.

### Can visibility be changed after asset creation?

Yes. Since `visibility` is a field on the `AssetEntity` object stored in the metadata service (as seen in [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts)), you can update it through standard asset update APIs. However, changing from `private` to `team` immediately exposes the asset to all teammates, while changing to `restricted` hides it from users who previously had access unless they hold explicit ACL grants.

### How does the proxy enforce visibility rules?

The proxy layer in [`MemoryProxy/src/meta/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/meta/client.ts) applies a **visibility whitelist** when processing list requests. It filters database queries to include only assets matching the requested visibility parameters (such as `visibility: 'team'`). This prevents unauthorized assets from ever reaching the client, providing defense-in-depth alongside the ACL system.