# How to Handle Version Type Inconsistencies Between `/v3/atomic/update` and `/v3/atomic/query` APIs in TencentDB Agent Memory

> Avoid version type inconsistencies in TencentDB Agent Memory APIs. Learn how to handle mismatches between v3 atomic update and query endpoints by preserving the type field client-side.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Always preserve the `type` field client-side when updating atomic memories because the `/v3/atomic/update` endpoint ignores type selectors while `/v3/atomic/query` filters by them, causing visibility mismatches if types drift.**

The TencentDB Agent Memory service provides atomic memory operations through the `/v3/atomic/*` endpoints, but subtle schema differences between update and query operations can lead to version type inconsistencies in the **L1 atomic layer**. In the TencentCloud/TencentDB-Agent-Memory repository, the TypeScript SDK implementation reveals that `updateAtomic()` omits the type field entirely, whereas `queryAtomic()` accepts it as an optional filter. Understanding this divergence is essential for maintaining data consistency across session-based memory operations.

## Understanding the API Schema Divergence

The atomic memory layer treats `type` as a classification enum (defined in [`src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/types.ts)), yet the two primary endpoints handle this field asymmetrically. This asymmetry creates a scenario where an updated memory item may disappear from filtered queries if the client assumes the server maintains type metadata during updates.

In [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts), the `updateAtomic()` method (lines 69-77) constructs a request body containing only `session_id`, `id`, `content`, and `background`—**deliberately excluding the `type` field**. Conversely, the `queryAtomic()` method (lines 79-86) accepts an optional `type` parameter that filters the result set to specific atomic categories such as Note (0), Fact (1), or Preference (2).

## Root Cause of Version Type Mismatches

When you call `updateAtomic()`, the server updates the memory entry without validating or preserving the type metadata in the request payload. Because the endpoint cannot receive a `type` parameter, it updates the content while retaining whatever type was previously stored server-side. However, if your application logic assumes a specific type association and later queries using `queryAtomic({ type: 1 })`, the updated record remains invisible if the server-side type differs from the query filter.

This behavior means **updates are type-agnostic while queries are type-sensitive**, creating a consistency gap when client applications do not explicitly track atomic memory types between operations.

## Strategies for Maintaining Type Consistency

### Preserve Type During Updates via Client-Side State

To prevent atomic memories from vanishing from filtered queries, retrieve the existing type before updating. Query the specific memory by ID to capture its current `type` value, then maintain that value in your application state.

```typescript
import { MemoryClient } from '@tencentdb/agent-memory';

const client = new MemoryClient({ baseURL: 'https://api.tencentdb.com' });

// Retrieve existing memory to capture type
const { items } = await client.queryAtomic({
  id: 'atom-123',
  type: 1  // Fact
});

if (!items?.length) throw new Error('Memory not found');
const atomic = items[0];

// Update content while preserving the original type client-side
await client.updateAtomic({
  id: atomic.id,
  session_id: atomic.session_id,
  content: 'Updated factual information',
  background: atomic.background
  // Note: No type field is sent to the server
});

```

### Handle Type Migrations Through Deletion and Recreation

The atomic layer does not support in-place type mutation through `updateAtomic()`. If you must change a memory from Fact (1) to Note (0), delete the existing entry and create a new one with the desired type.

```typescript
// Delete the old type
await client.deleteAtomic({ id: 'atom-123', session_id: 'sess-abc' });

// Recreate with new type
await client.createAtomic({
  session_id: 'sess-abc',
  content: 'Migrated content',
  type: 0,  // Now a Note
  background: 'Preserved context'
});

```

### Standardize Query Patterns Across Your Application

Always specify the `type` parameter in `queryAtomic()` calls to ensure predictable results. Omitting the type returns all atomic items regardless of classification, which masks potential inconsistencies.

```python
from tencentdb_agent_memory import MemoryClient

client = MemoryClient(base_url='https://api.tencentdb.com')

# Explicit type filtering prevents silent omissions

facts = client.query_atomic(type=1, limit=50)  # type=1 for Facts

for fact in facts['items']:
    print(f"Fact {fact['id']}: {fact['content']}")

```

### Synchronize Type Handling Across SDK Languages

The schema divergence exists across all official SDKs (TypeScript, Python, Go) because they share the same underlying REST contract defined in [`src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/types.ts). Ensure your consistency validation logic runs identically regardless of the language binding used in your stack.

## Direct API Comparison

The following cURL examples illustrate the structural difference between the update and query payloads as implemented in the TencentDB Agent Memory service.

**Update Operation** ([`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts), lines 69-77):

```bash
curl -X POST https://api.tencentdb.com/v3/atomic/update \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc",
    "id": "atom-456",
    "content": "Updated content",
    "background": "New context"
  }'

# Note: No "type" field exists in the request schema

```

**Query Operation** ([`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts), lines 79-86):

```bash
curl -X POST https://api.tencentdb.com/v3/atomic/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc",
    "type": 0,
    "limit": 10
  }'

# The "type" field optionally filters by Note (0), Fact (1), or Preference (2)

```

## Summary

- **The `/v3/atomic/update` endpoint** cannot receive a `type` parameter according to the SDK source in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts), making it blind to type classifications during updates.
- **The `/v3/atomic/query` endpoint** accepts an optional `type` filter, meaning queries may exclude updated memories if the client does not track types independently.
- **Always query before updating** to capture the current type, or maintain type metadata in your application state to ensure updated memories remain discoverable.
- **Recreate rather than update** when changing atomic memory types, as the atomic layer prohibits in-place type mutation.
- **Use consistent type enums** (0=Note, 1=Fact, 2=Preference) across all SDK operations as defined in [`src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/types.ts).

## Frequently Asked Questions

### Why does the updateAtomic method exclude the type field?

The `updateAtomic` method in [`src/v3/client.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/client.ts) (lines 69-77) follows the `/v3/atomic/update` API contract, which treats atomic memory updates as content-only operations. The server-side implementation preserves the existing type metadata internally, but because the request schema lacks a `type` property, clients cannot specify or override the type during the update. This design assumes type immutability for existing atomic entries.

### What happens if I update a memory and then query with a type filter?

If you query using `queryAtomic({ type: 1 })` after updating an item, the memory will appear only if its server-side type matches the filter. Since `updateAtomic` cannot modify type, the record remains visible under its original classification. However, if you previously assumed a different type or if multiple processes manipulate the same session, the visible set may appear inconsistent with your client-side expectations.

### Can I change the type of an existing atomic memory without deleting it?

No. The TencentDB Agent Memory atomic layer does not support in-place type changes. According to the API documentation and source code in [`v3-api-memorycore-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3-api-memorycore-doc.md) and [`src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/types.ts), you must delete the existing atomic memory and recreate it with the new `type` value. Attempting to work around this by manipulating raw requests will fail schema validation.

### Which SDK versions are affected by this inconsistency?

All official SDK versions (TypeScript, Python, Go, Java) share the same request schemas defined in the core repository, specifically referencing [`src/v3/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/v3/types.ts) for type definitions. The asymmetry between `updateAtomic` and `queryAtomic` exists at the protocol level (`/v3/atomic/update` vs `/v3/atomic/query`), meaning every SDK binding inherits this behavior regardless of version or language.