# TencentDB-Agent Memory v3 Core Endpoints: How to Read and Write L3 Core/Persona Data

> Learn how to use TencentDB-Agent-Memory v3 core endpoints for L3 Core/Persona read and write operations. Access versioned persona content via RPC with isolation fields.

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

---

**The `/v3/core/read` and `/v3/core/write` endpoints provide POST-based RPC access to the L3 Core/Persona document, accepting isolation fields (team_id, agent_id, user_id, task_id) and returning versioned persona content as JSON.**

The TencentDB-Agent-Memory repository implements a **MemoryCore service** that manages hierarchical memory layers, with **L3 Core (Persona)** representing the highest-level identity document stored as [`persona.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/persona.md). This guide covers the complete v3 API surface for reading and writing this critical persona data, based on the actual implementation in `TencentCloud/TencentDB-Agent-Memory`.

## What Are the v3 Core/Persona Endpoints?

The MemoryCore service exposes exactly **two v3 endpoints** for L3 Core/Persona operations:

| Endpoint | Purpose | HTTP Method |
|----------|---------|-------------|
| `/v3/core/read` | Retrieve persona content (latest or specific version) | POST |
| `/v3/core/write` | Create new persona version with updated content | POST |

Both endpoints follow the **v3 RPC envelope format**:

```json
{
  "code": 0,
  "message": "ok",
  "request_id": "...",
  "data": { ... }
}

```

The service runs on **port 8420** and requires **data-plane authentication** (auth layer 1 + `x-tdai-service-id` header) as documented in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) lines 9-18.

## Understanding the Isolation Model

Every v3 Core/Persona request operates within a **multi-tenant namespace** defined by four identifiers. These fields determine which persona document you access:

- `team_id` — Tenant/organization boundary
- `agent_id` — Specific agent instance
- `user_id` — End-user context
- `task_id` — Optional task-scoped override

**Supply these either in the JSON body or as HTTP headers.** Body values take precedence when both are present. The L3 Core is **team + agent + user scoped** — meaning two users under the same agent maintain separate persona histories.

## POST /v3/core/read: Retrieving Persona Content

The read endpoint fetches the [`persona.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/persona.md) content for a given isolation context, with optional version targeting.

### Request Structure

```json
{
  "team_id": "t_1",
  "agent_id": "agt_1", 
  "user_id": "u_1",
  "task_id": "task_1",
  "version": 3
}

```

The `version` field is **optional** — omit it to retrieve the latest version.

### Success Response (data field)

```json
{
  "content": "# Persona\nYou are a senior DevOps engineer...",

  "version": 3,
  "team_id": "t_1",
  "agent_id": "agt_1",
  "created_at": "2024-01-15T08:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}

```

**Key behavior:** If no persona exists, the API returns HTTP 200 with `content: null` — this is not an error condition.

## POST /v3/core/write: Creating New Persona Versions

The write endpoint **always creates a new version** — it does not support in-place updates. This append-only design preserves complete audit history.

### Request Structure

```json
{
  "team_id": "t_1",
  "agent_id": "agt_1",
  "user_id": "u_1",
  "content": "# Persona\nYou are a senior DevOps engineer who loves automation."

}

```

### Success Response (data field)

```json
{
  "version": 4,
  "updated_at": "2024-01-21T09:15:30Z"
}

```

The server increments the version counter automatically and records the server timestamp. The `content` field supports full Markdown — this is the raw [`persona.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/persona.md) document body.

## Code Implementation: TypeScript SDK

The official SDK in [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) provides typed helpers for both operations.

### Reading with the SDK

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

const client = new MemoryCoreClient({
  baseURL: 'http://localhost:8420',
  authToken: 'Bearer <KERNEL_AUTH_TOKEN>',
  serviceId: 'my-instance-id',  // maps to x-tdai-service-id header
});

const readResponse = await client.v3.core.read({
  team_id: 't_1',
  agent_id: 'agt_1',
  user_id: 'u_1',
  // version: 3,  // optional: omit for latest
});

console.log('Content:', readResponse.data.content);
console.log('Version:', readResponse.data.version);

```

The SDK method at line 356 translates this to `POST /v3/core/read` with proper header injection.

### Writing with the SDK

```typescript
const writeResponse = await client.v3.core.write({
  team_id: 't_1',
  agent_id: 'agt_1', 
  user_id: 'u_1',
  content: `# Persona

You are a senior DevOps engineer specializing in:
- Terraform infrastructure
- CI/CD pipeline optimization
- Cost-aware cloud architecture`
});

console.log('New version:', writeResponse.data.version);

```

## Raw HTTP Examples with cURL

For integration testing or non-TypeScript environments, use these direct HTTP calls:

### Read Request

```bash
curl -X POST http://localhost:8420/v3/core/read \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <KERNEL_AUTH_TOKEN>" \
  -H "x-tdai-service-id: my-instance-id" \
  -d '{
    "team_id": "t_1",
    "agent_id": "agt_1",
    "user_id": "u_1"
  }'

```

### Write Request

```bash
curl -X POST http://localhost:8420/v3/core/write \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <KERNEL_AUTH_TOKEN>" \
  -H "x-tdai-service-id: my-instance-id" \
  -d '{
    "team_id": "t_1",
    "agent_id": "agt_1",
    "user_id": "u_1",
    "content": "# Persona\nYou are a senior DevOps engineer."

  }'

```

## Server-Side Routing Architecture

The v3 endpoints share implementation with v2 through a unified routing layer. In [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts) lines 169-429, the same handler functions serve both API versions:

- `/core/read` (v2) and `/v3/core/read` → identical read handler
- `/core/write` → write handler (v3 path added in v3 router)

This design ensures behavioral consistency while allowing v3-specific envelope formatting.

## Error Handling Reference

Both endpoints return standard data-plane error responses:

| HTTP Status | Cause | Typical Scenario |
|-------------|-------|----------------|
| 400 | Invalid payload | Missing required fields, malformed JSON |
| 403 | Ownership mismatch | Isolation fields don't match authenticated context |
| 404 | Not found | Only for read — version or file doesn't exist |
| 503 | Storage unavailable | Backend storage service degradation |

Error responses use **plain text messages** per the v3 convention documented in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) lines 57-70.

## Source Code Locations

| File | Purpose | Key Lines |
|------|---------|-----------|
| [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) | Canonical API specification | Read: L4-L12; Write: L14-L18 |
| [`sdk/memory-core/typescript/src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/client.ts) | TypeScript SDK implementation | `read`: L356; `write`: adjacent |
| [`MemoryCore/src/gateway/v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/v2-router.ts) | Server route registration | L169-L429 |

## Summary

- **`/v3/core/read`** retrieves L3 Persona content with optional version pinning; returns `null` content for missing files
- **`/v3/core/write`** creates immutable new versions; returns incremented version number and timestamp
- Both require **POST requests** with four isolation identifiers (team, agent, user, task)
- **Port 8420** serves all MemoryCore traffic; authentication uses kernel tokens plus service-id headers
- **Append-only versioning** guarantees audit trail; there are no deletes or updates in-place
- Implementation spans [`v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3-api-memorycore-doc.md), [`v2-router.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v2-router.ts), and the TypeScript SDK client

## Frequently Asked Questions

### Does the v3 Core API support GET requests?

**No.** As implemented in [`MemoryCore/v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/v3-api-memorycore-doc.md) lines 9-18, all v3 endpoints are **POST-only** including reads. The RPC-style design uses JSON bodies for parameters rather than URL query strings.

### What happens if I omit the version parameter in a read request?

The API returns the **latest version** for the specified isolation context. If no persona has ever been written, you receive HTTP 200 with `content: null` — this is expected behavior, not an error.

### Can I update an existing persona version in place?

**No.** The `/v3/core/write` endpoint is **append-only**. Every write creates a new version with an incremented integer. This immutability design supports complete history tracking for audit and rollback purposes.

### Where does the `x-tdai-service-id` header come from?

This header identifies the specific MemoryCore instance within the TencentDB-Agent kernel. The TypeScript SDK accepts it as the `serviceId` constructor option and injects it automatically.