@tencentdb-agent-memory/memory-sdk-ts-v2

@tencentdb-agent-memory/memory-sdk-ts

TypeScript SDK for TencentDB Agent Memory, supporting both the v2 compatibility API and the v3 strict-isolation data-plane API.

• Default MemoryClient remains v2-compatible for existing code.
• New code should prefer @tencentdb-agent-memory/memory-sdk-ts/v3.
• The root entry also exports V3MemoryClient for environments that cannot use subpath imports.

Install

npm install @tencentdb-agent-memory/memory-sdk-ts

Quick Start

v3 recommended

v3 differences:

• paths use /v3/*;
• constructor requires teamId, agentId, and userId;
• sessionId is optional:
  • present: L0/L1 are scoped to one session;
  • omitted or cleared with withIsolation({ sessionId: null }): L0/L1 aggregate across sessions for the same team+agent+user;
  • L2/L3 are team+agent profile data and do not consume sessionId;
• Offload and COS artifact reading remain on the v2 client.

import { MemoryClient } from "@tencentdb-agent-memory/memory-sdk-ts/v3";

const client = new MemoryClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: "your-gateway-api-key",
  serviceId: "your-memory-instance-id",
  teamId: "team-xxx",
  agentId: "agt-xxx",
  userId: "usr-xxx",
  sessionId: "sess-1",
});

await client.addConversation({
  messages: [
    { role: "user", content: "Hello" },
    { role: "assistant", content: "Hi!" },
  ],
});

const l0 = await client.queryConversation({ limit: 20, offset: 0 });
const allSessions = await client.withIsolation({ sessionId: null }).queryConversation({ limit: 20 });
const l1 = await client.searchAtomic({ query: "user preferences", limit: 5 });
const scene = await client.readScenario({ path: "work.md" });
const core = await client.readCore();

Root import variant:

import { V3MemoryClient } from "@tencentdb-agent-memory/memory-sdk-ts";

v2 compatibility

import { MemoryClient } from "@tencentdb-agent-memory/memory-sdk-ts";

const client = new MemoryClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: "your-gateway-api-key",
  serviceId: "your-memory-instance-id",
});

await client.addConversation({
  session_id: "sess-1",
  messages: [{ role: "user", content: "Hello" }],
});

API Methods

v3 data plane

Layer	Method	Endpoint
L0	addConversation()	POST /v3/conversation/add
L0	queryConversation()	POST /v3/conversation/query
L0	searchConversation()	POST /v3/conversation/search
L0	deleteConversation()	POST /v3/conversation/delete
L0	countConversation()	POST /v3/conversation/count
L1	updateAtomic()	POST /v3/atomic/update
L1	queryAtomic()	POST /v3/atomic/query
L1	searchAtomic()	POST /v3/atomic/search
L1	deleteAtomic()	POST /v3/atomic/delete
L1	countAtomic()	POST /v3/atomic/count
L2	listScenarios()	POST /v3/scenario/ls
L2	readScenario()	POST /v3/scenario/read
L2	writeScenario()	POST /v3/scenario/write
L2	rmScenario()	POST /v3/scenario/rm
L2	countScenario()	POST /v3/scenario/count
L3	readCore()	POST /v3/core/read
L3	writeCore()	POST /v3/core/write
L3	countCore()	POST /v3/core/count

v2 compatibility data plane

The root MemoryClient still maps to /v2/* for L0-L3 and Offload, preserving existing integrations.

MetadataClient (v3 management plane)

MetadataClient wraps the gateway's v3 metadata management endpoints (/v3/meta/* — 54 routes aligned with Panel META_ACTIONS, including user-key/*) plus /v3/knowledge/* Knowledge CRUD (5 routes). Auth: Bearer + x-tdai-service-id, optional x-tdai-user-key.

import { MetadataClient } from "@tencentdb-agent-memory/memory-sdk-ts";

const meta = new MetadataClient({
  endpoint: "http://127.0.0.1:8420",
  apiKey: "verify-token",        // gateway Bearer (KERNEL_AUTH_TOKEN)
  serviceId: "knowledge-debug",  // x-tdai-service-id
  // userKey: "...",             // optional; needed by system_admin endpoints (user/create, user/delete)
});

Knowledge management (/v3/knowledge/*)

Manage Knowledge entity metadata (types: wiki | code-graph). These are management-plane CRUD — metadata only. Actually searching wiki content, reading pages, or syncing repos is the Knowledge Service data-plane's job, not this client.

Method	Endpoint	Notes
createKnowledge()	POST /v3/knowledge/create	upsert metadata (idempotent; re-post overwrites)
getKnowledge(id, teamId?)	POST /v3/knowledge/get	get one by id
updateKnowledge()	POST /v3/knowledge/update	partial update (name/summary/service_url/repo_url/branch)
deleteKnowledge(ids, teamId?)	POST /v3/knowledge/delete	batch delete (≤100)
listKnowledge()	POST /v3/knowledge/list	list by team_id, optional type filter / batch id lookup

// Register a wiki knowledge source
const k = await meta.createKnowledge({
  knowledge_id: "wiki-docs",
  type: "wiki",
  service_url: "http://127.0.0.1:8421/v3",  // Knowledge Service data-plane URL
  name: "Team Docs Wiki",
  summary: "Internal tech docs",
  team_id: "team-1",
  user_id: "usr-1",
});
console.log(k.knowledge_id, k.type, k.created_at);

// List all code-graphs under a team
const list = await meta.listKnowledge({ team_id: "team-1", type: "code-graph" });
console.log(list.items, list.total);

// Rename / change service_url
await meta.updateKnowledge({ knowledge_id: "wiki-docs", name: "Renamed Wiki" });

// Batch delete
await meta.deleteKnowledge(["wiki-docs", "cg-repo-1"], "team-1");

Return types: KnowledgeEntity / KnowledgeListResult { items, total } / BatchDeleteResult { deleted_ids, failed }.

Error Handling

All non-zero code responses throw TDAMError:

import { TDAMError } from "@tencentdb-agent-memory/memory-sdk-ts";

try {
  await client.readCore();
} catch (e) {
  if (e instanceof TDAMError) {
    console.error(`code=${e.code} message=${e.message} request_id=${e.requestId}`);
  }
}

Build & Pack

npm run build
npm test
npm pack

License

MIT