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

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

{
  "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 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 content for a given isolation context, with optional version targeting.

Request Structure

{
  "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)

{
  "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

{
  "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)

{
  "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 document body.

Code Implementation: TypeScript SDK

The official SDK in sdk/memory-core/typescript/src/v3/client.ts provides typed helpers for both operations.

Reading with the SDK

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

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

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

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 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 lines 57-70.

Source Code Locations

File	Purpose	Key Lines
MemoryCore/v3-api-memorycore-doc.md	Canonical API specification	Read: L4-L12; Write: L14-L18
sdk/memory-core/typescript/src/v3/client.ts	TypeScript SDK implementation	read: L356; write: adjacent
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, 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 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.

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