How to Troubleshoot TencentDB Agent Memory Connection Issues: 8 Debug Steps

Enable verbose logging via LOG_LEVEL=debug and trace requests through guard-adapter.ts and pipeline-manager.ts to isolate connection failures in the HTTP gateway or LLM resolver.

TencentDB-Agent-Memory is a distributed memory system for AI agents composed of loosely-coupled HTTP services. When you troubleshoot TencentDB Agent Memory connection issues, you need to trace requests through the MemoryProxy, MemoryCore gateway, and Pipeline Manager to identify where the flow breaks.

Understand the Component Architecture

Before debugging, map your request path to these source files:

• MemoryCore gateway (MemoryCore/src/gateway/server.ts) – The entrypoint HTTP server that routes requests to skill handlers.
• MemoryProxy (MemoryProxy/src/guard-adapter.ts) – The reverse-proxy layer that handles cost-guarding and telemetry forwarding via resolveForwardTarget.
• Pipeline Manager (MemoryCore/src/utils/pipeline-manager.ts) – Orchestrates L1/L2/L3 processing queues and logs state transitions.
• Serial Queue (MemoryCore/src/utils/serial-queue.ts) – The FIFO queue implementation with debug hooks used by the pipeline manager.
• LLM Provider Resolver (MemoryCore/src/adapters/standalone/llm-provider-resolver.ts) – Resolves API keys and model configurations for L1 extraction.
• CLI Utilities (MemoryCore/bin/seed-v2.mjs) – Scripts for seeding test data and inspecting local memory stores.

Enable Verbose Logging Globally

All internal components respect the LOG_LEVEL environment variable. Setting it to debug activates the logger?.debug?. calls scattered throughout the codebase, including lines 277–388 in pipeline-manager.ts and lines 4–12 in guard-adapter.ts.

export LOG_LEVEL=debug
export TDAI_GATEWAY_CONFIG=./tdai-gateway.standalone.yaml
export TDAI_GATEWAY_API_KEY="your-strong-token"
node --import tsx MemoryCore/src/gateway/server.ts

Debug logs reveal queue enqueue operations, passthrough decisions, and quota checks, giving you a step-by-step trace of a request’s journey through the system.

Verify the HTTP Gateway Health

Confirm the gateway process is listening and responsive by querying the health endpoint.

curl -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" http://127.0.0.1:8420/health

# Expected: {"status":"ok"}

Non-200 responses indicate binding errors or authentication failures. Check the startup logs for TDAI_GATEWAY_HOST and TDAI_GATEWAY_PORT configuration issues in the resolved configuration.

Trace Requests Through the MemoryProxy

When a request hits the proxy, resolveForwardTarget in guard-adapter.ts (lines 4–13) decides between direct passthrough or guarded routing:

• Passthrough – Logged as guard_adapter.passthrough with a reason field.
• Guarded – Subsequent logs show extension_unavailable if the cost-guard extension is missing.

If you suspect the guard is interfering with connections, bypass it:

export TDAI_COST_GUARD_ENABLED=false

Watch the logs change from extension_disabled to default_passthrough, confirming the proxy is not blocking your request.

Inspect Pipeline Queue State

The pipeline manager maintains three independent queues (l1Queue, l2Queue, l3Queue). With LOG_LEVEL=debug, the manager wires debug loggers at lines 287–292 in pipeline-manager.ts:

if (this.logger?.debug) {
  const debugFn = (msg: string) => this.logger?.debug?.(`${TAG} ${msg}`);
  this.l1Queue.setDebugLogger(debugFn);
  this.l2Queue.setDebugLogger(debugFn);
  this.l3Queue.setDebugLogger(debugFn);
}

Look for these log patterns to identify stalls:

• [l1-debug] Enqueuing L1 (queue=queue-name) – Request entered L1 extraction.
• [l1-debug] L1 already queued, skipping – Indicates a stuck L1 process, often due to a malformed conversation payload or missing LLM runner.
• [l3-debug] L3 complete – Request finished processing.

If L1 extraction hangs, verify that pipeline-factory.ts (lines 408–453) is not emitting “No OpenClaw config and no LLM runner, skipping L1 extraction.”

Validate Configuration Precedence

Configuration resolution follows a strict order. If you encounter unexpected defaults, verify which file is loaded:

1. TDAI_GATEWAY_CONFIG environment variable (highest priority).
2. tdai-gateway.yaml in the current directory.
3. tdai-gateway.yaml in the data directory.

Print the resolved configuration at runtime:

node --import tsx -e "console.log(require('./MemoryCore/src/config').loadConfig())"

The loader implementation lives in MemoryCore/src/config.ts and clarifies precedence between environment variables and YAML files.

Check Skill Module and LLM Connectivity

Skill-related endpoints (/v3/skill/*) depend on the LLM provider resolver. If L1 extraction fails, check that the resolver can locate a valid TDAI_LLM_API_KEY and model configuration in adapters/standalone/llm-provider-resolver.ts.

When the cost-guard extension is enabled, telemetry flows through forwardTelemetry in guard-adapter.ts (lines 42–48). Ensure destination URLs like Opik or Langfuse are reachable; missing tokens surface as HTTP 401 errors in the proxy logs.

Use CLI Utilities for Data Inspection

Two built-in commands help establish a baseline:

• Read local memory – Dumps recent conversation records from the SQLite store.

  npm run read-local-memory

• Seed V2 – Loads a deterministic dataset for reproducible debugging.

  npm run seed-v2

Both commands respect the same environment configuration as the gateway, allowing you to compare clean runs against problematic states using MemoryCore/bin/seed-v2.mjs.

Summary

• Set LOG_LEVEL=debug to activate granular tracing in pipeline-manager.ts and guard-adapter.ts.
• Query /health with your TDAI_GATEWAY_API_KEY to verify gateway availability.
• Analyze guard_adapter.passthrough logs to determine if the proxy or cost-guard is blocking requests.
• Monitor [l1-debug], [l2-debug], and [l3-debug] messages to pinpoint pipeline stalls.
• Validate that TDAI_LLM_API_KEY is configured and the resolver in llm-provider-resolver.ts can initialize the LLM runner.
• Use npm run seed-v2 and npm run read-local-memory for deterministic reproduction and data inspection.

Frequently Asked Questions

Why is my TencentDB Agent Memory gateway returning 401 Unauthorized?

The gateway requires the Authorization: Bearer header matching your TDAI_GATEWAY_API_KEY. Verify the header is present and the token matches the value used at startup. Check the gateway logs for guard-adapter.ts entries indicating token validation failures.

How do I disable the cost-guard extension to rule out proxy issues?

Set the environment variable TDAI_COST_GUARD_ENABLED=false before starting the gateway. This forces guard-adapter.ts to use default passthrough mode, bypassing the private cost-guard extension and its telemetry forwarding to external services.

What causes “No OpenClaw config and no LLM runner, skipping L1 extraction”?

This error in pipeline-factory.ts (lines 408–453) indicates the system cannot locate a valid LLM configuration. Ensure TDAI_LLM_API_KEY is exported and that adapters/standalone/llm-provider-resolver.ts can resolve your model provider. Without an LLM runner, L1 memory extraction is skipped, breaking downstream processing.

How can I check if the pipeline queues are processing requests?

Enable LOG_LEVEL=debug and look for [l1-debug] Enqueuing L1 and [l3-debug] L3 complete in the logs. If you see [l1-debug] L1 already queued, skipping repeatedly, the L1 queue is stuck, usually due to a hanging LLM call or malformed payload in the serial queue.

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