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

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), 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, 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.

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.

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

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. 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, lines 69-77):

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, lines 79-86):

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

Frequently Asked Questions

Why does the updateAtomic method exclude the type field?

The updateAtomic method in 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 and 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 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.

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