# How TencentDB Agent Memory Implements Long-Term Personalization Through Layered Memory Architecture

> Explore TencentDB Agent Memory's layered architecture L0-L3 for efficient long-term personalization. Isolate data, retrieve persona knowledge, and maintain scope boundaries.

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

---

**TencentDB Agent Memory implements long-term personalization through a four-tier hierarchy (L0-L3) that isolates raw conversation data into progressive abstractions, enabling efficient retrieval of user-specific persona knowledge while maintaining strict personal versus team scope boundaries.**

TencentDB Agent Memory uses a hierarchical layering system to transform ephemeral chat logs into persistent, personalized knowledge. This architecture separates short-term conversational context from long-term user traits through distinct abstraction layers. The implementation ensures that AI agents retain contextual awareness across sessions while respecting privacy boundaries between individual users and shared team resources.

## The Four-Tier Memory Layer Architecture

The repository organizes memory into a cascade of four distinct layers that progressively abstract raw interaction data into reusable persona knowledge. According to the [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) in the repository root, the system visualizes this hierarchy as **"L0 Conversation → L1 Atom → L2 Scenario → L3 Persona"**.

**L0 (Raw Conversation)** stores complete chat logs exactly as they arrive, preserving the full verbatim history of interactions.

**L1 (Atomic Atoms)** extracts individual decisions, facts, or actions from L0 data, creating discrete, searchable units of information.

**L2 (Scenario-Level Structures)** groups related atoms into coherent situations or workflows, representing contextual groupings of related activities.

**L3 (Persona-Level Knowledge)** captures long-term preferences, user-specific traits, and skill definitions that persist across sessions and define the user's unique interaction profile.

## Hierarchical Retrieval and Fallback Strategy

Both generation and retrieval operations follow the same layered path described in [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md). When processing a request, the system first attempts to satisfy information needs from the most specific layers (L2 and L3). If the required detail is absent, it executes a controlled fallback through broader layers (L1 to L0).

This fallback mechanism employs **BM25** full-text search combined with **vector similarity** scoring, fused through **Reciprocal Rank Fusion (RRF)** to rank results across abstraction levels. This design guarantees that large language models never exhaust available context while maintaining prompt sizes within model token limits. The retrieval logic prioritizes high-level, personalized knowledge before resorting to raw conversation logs, optimizing both performance and relevance.

## Personal vs. Team Scope Implementation

The memory system implements strict data isolation through dual-scope semantics that distinguish between individual user assets and shared team resources.

In [`MemoryCore/src/core/skill/skill-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/skill/skill-core.ts) at line 487, the implementation filters queries by `user_id` only when no `team_id` is present, effectively switching between personal and shared scopes. Personal assets reside in the L3 Persona layer but carry only a `user_id` tag with no `team_id`, restricting visibility to the creator and authorized administrators.

Conversely, shared assets include a `team_id` field, making them accessible to all teammates while preserving ownership metadata. The UI components in [`MemoryPanel/web/src/i18n/zh-CN.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/i18n/zh-CN.ts) (lines 454-462) expose this distinction through labels such as "My Assets" (个人资产分配) and toggles for **shared** versus **private** visibility.

The proxy handling logic in [`MemoryProxy/src/skill/skill-bridge.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/skill/skill-bridge.ts) (lines 596-644) normalizes these semantics at the system boundary, ensuring consistent enforcement of scope rules across the architecture.

## Practical Implementation Examples

The following TypeScript example demonstrates creating a personal memory prompt at the atomic layer:

```typescript
// Example: Create a personal memory prompt at layer L1
await prompts.create({
  name: "Decision Extractor",
  layer: "l1",                     // L1 = atom layer
  prompt: "Extract explicit decisions."
});

// Apply the prompt only for the current user (personal scope)
await prompts.apply(created.memory_prompt_id, {
  layer: "l1",
  agent_ids: ["agent-1"],
  // No team_id → personal scope; only the creator sees the effect
});

```

When retrieving effective prompts, the SDK automatically enforces scope boundaries:

```python

# Example: Retrieve effective prompts for a personal user

effective = await prompts.get_effective(layer="l1")

# The SDK automatically adds `user_id` filter when `team_id` is absent

```

The TypeScript SDK in [`sdk/memory-core/typescript/src/v3/memory-prompt-client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/memory-prompt-client.ts) accepts the `layer` parameter (e.g., `"l1"`, `"l2"`, `"l3"`) to target specific abstraction levels during memory operations.

## Summary

- **TencentDB Agent Memory** organizes data into four hierarchical layers (L0-L3) that progressively abstract raw conversations into persona-level knowledge.
- The **retrieval system** prioritizes high-level layers (L2/L3) and falls back to raw logs (L0) only when necessary, using BM25, vector similarity, and RRF ranking.
- **Personal scope** relies on `user_id` filtering when `team_id` is absent, while shared assets use `team_id` for team-wide visibility, as implemented in [`skill-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/skill-core.ts).
- This **layered architecture** enables long-term personalization by condensing low-level details into persistent user traits while maintaining strict privacy boundaries.

## Frequently Asked Questions

### What are the four layers in TencentDB Agent Memory's personalization system?

The system uses **L0** (Raw Conversation) for complete chat logs, **L1** (Atom) for extracted decisions and facts, **L2** (Scenario) for grouped workflow contexts, and **L3** (Persona) for long-term user preferences and traits. This hierarchy is documented in the repository's [`README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/README.md) as "L0 Conversation → L1 Atom → L2 Scenario → L3 Persona".

### How does the retrieval system handle missing data in higher memory layers?

When specific information is absent from L2 or L3, the system executes a **fallback retrieval** through lower layers using BM25 full-text search combined with vector similarity, ranked via Reciprocal Rank Fusion (RRF). This ensures the LLM receives relevant context from L1 or L0 only when higher-level abstractions prove insufficient.

### What is the difference between personal and team scope in memory assets?

**Personal assets** carry only a `user_id` tag and no `team_id`, restricting access to the individual creator. **Team assets** include a `team_id` field, making them visible to all team members. The system checks for `team_id` presence in [`MemoryCore/src/core/skill/skill-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/skill/skill-core.ts) to determine which filtering logic to apply.

### How does the codebase enforce personal vs team visibility boundaries?

Scope enforcement occurs at multiple levels: the **Skill Core** filters queries by `user_id` when `team_id` is absent (line 487), the **Memory Proxy** normalizes scope semantics in the bridge layer (lines 596-644), and the **UI layer** distinguishes between "My Assets" and shared resources through internationalization keys in [`zh-CN.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/zh-CN.ts) (lines 454-462).