Understanding Visibility Semantics for Memory Assets in TencentDB Agent Memory

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:

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. 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, 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 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:

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 accept visibility as a query parameter to filter results:

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:

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:

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 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), 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}