# MemoryCore: Key Capabilities of the TencentDB Agent Memory System

> Explore MemoryCore's key capabilities, the TencentDB Agent Memory system's engine. Discover unified storage, hierarchical processing, hybrid retrieval, and HTTP APIs for AI.

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

---

**MemoryCore is the central memory and metadata engine of the TencentDB Agent Memory system, providing unified storage, hierarchical memory processing (L0-L3), hybrid retrieval, and multi-tenant HTTP APIs for AI agent applications.**

MemoryCore serves as the backbone of the TencentCloud/TencentDB-Agent-Memory repository, offering a self-contained runtime for persisting and recalling conversational context. It implements a four-layer memory hierarchy and exposes rich TypeScript/Python SDKs and HTTP endpoints that enable agents to capture interactions, extract skills, and retrieve relevant context with minimal configuration.

## Hierarchical Memory Storage and Processing

MemoryCore implements a sophisticated **four-layer memory hierarchy** that processes raw conversations into structured, retrievable knowledge. The core abstractions in `MemoryCore/src/core/` handle the pipeline that transforms data across these levels:

- **L0 (Conversations)**: Raw dialogue turns captured from agent interactions
- **L1 (Atomic Memories)**: Distilled facts and insights extracted from conversations
- **L2 (Scenarios)**: Contextual situations that group related atomic memories
- **L3 (Profiles)**: Persistent user and agent characteristics aggregated over time

The storage layer persists these entities and manages their lifecycle, including creation, updating, and aggregation operations.

## Hybrid Memory Recall

The recall system supports **keyword, embedding, and hybrid retrieval** strategies to surface relevant context. BM25 text search works out-of-the-box without external dependencies, while vector similarity search can be enabled via any OpenAI-compatible embedding API.

This dual approach allows agents to retrieve exact matches for known entities while also discovering semantically related information through vector search.

## Knowledge and Asset Metadata Management

MemoryCore maintains comprehensive registries for operational metadata. The **knowledge metadata registry** tracks external sources such as Wiki systems and Code Graphs, recording their identifiers, types, status, associations, and service locations.

The **asset metadata management** system handles organizational structure, including users, teams, agents, tasks, skills, knowledge assets, memberships, ownership rules, and access relationships. This ensures that memory operations respect organizational boundaries and permission models.

## Skill Memory Lifecycle

The Skill Memory subsystem provides full lifecycle management for agent capabilities. Located within the core storage layer, it handles:

- **Creation and versioning** of skill definitions
- **Resource handling** for skill dependencies
- **Search and routing** to match requests with appropriate skills
- **Conversation-driven extraction** to generate new skills from demonstrated interactions

Agents can register capabilities programmatically and retrieve them contextually during task execution.

## Unified API Surface and Multi-Tenant Security

MemoryCore exposes a **secure, multi-tenant HTTP API** (versions v2 and v3) alongside TypeScript and Python SDKs. Every v3 request requires tenant isolation headers to guarantee data separation:

- `x-tdai-team-id`: Identifies the organizational tenant
- `x-tdai-agent-id`: Identifies the specific agent instance
- `x-tdai-user-id`: Identifies the end user

The gateway implementation in `MemoryCore/src/gateway/` routes these authenticated requests to the appropriate storage backends while enforcing access controls.

### Capturing Conversations

To persist a conversation turn (L0) via the v3 API:

```bash
curl -X POST http://127.0.0.1:8420/v3/conversation/capture \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-service-id: default" \
  -H "x-tdai-team-id: team-123" \
  -H "x-tdai-agent-id: agent-xyz" \
  -H "x-tdai-user-id: user-abc" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "sess-001",
        "turn_id": "turn-001",
        "role": "user",
        "content": "How do I reset my password?"
      }'

```

### Retrieving Atomic Memories

To recall relevant atomic memories (L1) using BM25 retrieval:

```bash
curl -X GET "http://127.0.0.1:8420/v3/atomic/search?query=reset+password&limit=5" \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "x-tdai-service-id: default" \
  -H "x-tdai-team-id: team-123" \
  -H "x-tdai-agent-id: agent-xyz" \
  -H "x-tdai-user-id: user-abc"

```

### Registering Knowledge Sources

To register a new Wiki knowledge source via the metadata API:

```bash
curl -X POST http://127.0.0.1:8420/v3/knowledge/register \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "wiki",
        "name": "ProductDocs",
        "status": "ready",
        "service_url": "http://wiki.internal/api",
        "metadata": { "language": "en" }
      }'

```

### Extracting Skills

To extract or utilize skills from conversation context:

```bash
curl -X POST http://127.0.0.1:8420/v3/skill/extract \
  -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "session_id": "sess-001",
        "skill_id": "skill-knowledge-base",
        "input": "Explain the steps for provisioning a new DB instance."
      }'

```

## Standalone Runtime Architecture

MemoryCore runs as a **lightweight gateway** defaulting to `127.0.0.1:8420`, requiring only SQLite and local file storage for operation. The `MemoryCore/Dockerfile` enables containerized deployment, while [`MemoryCore/tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/tdai-gateway.standalone.yaml) provides the default configuration template.

The system requires only a compatible LLM API endpoint for memory extraction operations, making it suitable for local development, single-node production deployments, or sidecar configurations in larger orchestration systems.

Adapters such as the OpenClaw plugin (`MemoryCore/openclaw-plugin/`) and Hermes provider (`MemoryCore/hermes-plugin/`) demonstrate how lightweight clients can integrate with the gateway using minimal boilerplate.

## Summary

- **MemoryCore** provides centralized memory management for AI agents through a four-layer hierarchy (L0-L3) that processes raw conversations into persistent profiles and scenarios.
- **Hybrid retrieval** combines BM25 keyword search with optional vector similarity for flexible context recall.
- **Metadata registries** track knowledge sources and organizational assets, enabling complex multi-agent and multi-team workflows.
- **Multi-tenant security** enforces strict isolation through required headers (`team_id`, `agent_id`, `user_id`) on every API request.
- **Standalone deployment** requires only SQLite and runs locally or in containers at `127.0.0.1:8420`, with adapters available for TypeScript and Python integration.

## Frequently Asked Questions

### What is the difference between L0 and L1 memory in MemoryCore?

**L0 memory represents raw conversation turns** captured directly from user-agent interactions, while **L1 atomic memories are distilled facts and insights** extracted from those conversations through LLM processing. The pipeline in `MemoryCore/src/core/` automatically promotes relevant L0 data to L1 based on importance and uniqueness criteria, making L1 optimized for retrieval and reuse.

### Does MemoryCore require an external vector database?

**No, MemoryCore does not require an external vector database for basic operation.** BM25 text retrieval works out-of-the-box using local SQLite storage. However, developers can enable embedding-based semantic search by configuring an OpenAI-compatible API endpoint in the gateway configuration, allowing hybrid retrieval without deploying separate vector infrastructure.

### How does MemoryCore ensure data isolation between different teams?

**MemoryCore enforces multi-tenancy through required HTTP headers** on every v3 API request: `x-tdai-team-id`, `x-tdai-agent-id`, and `x-tdai-user-id`. The gateway implementation in `MemoryCore/src/gateway/` uses these identifiers to partition data at the storage layer, ensuring that memory records, knowledge assets, and skill definitions remain isolated between tenants even when sharing the same runtime instance.

### Can MemoryCore run entirely offline or in air-gapped environments?

**Yes, MemoryCore supports fully offline operation** when configured with local LLM endpoints. The standalone runtime uses SQLite and local file storage by default, requiring no external services except for the optional embedding API. Organizations can deploy the containerized gateway using `MemoryCore/Dockerfile` and configure [`tdai-gateway.standalone.yaml`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/tdai-gateway.standalone.yaml) to point to internal LLM services, enabling complete air-gapped functionality.