# CodeGraph Tools in TencentDB Agent Memory: Complete API Reference

> Explore nine CodeGraph tools in TencentDB Agent Memory: get_info, search, explore, callers, callees, impact, node, status, and files. Access read-only LLM agent integration via the /v3/tools HTTP namespace.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: api-reference
- Published: 2026-08-27

---

**TencentDB Agent Memory exposes nine pre‑indexed CodeGraph query tools—`get_info`, `search`, `explore`, `callers`, `callees`, `impact`, `node`, `status`, and `files`—through the `/v3/tools` HTTP namespace for read‑only LLM agent integration.**

The TencentCloud/TencentDB-Agent-Memory repository ships with a built‑in **CodeGraph** asset that allows LLM agents to interrogate indexed codebases without modifying source. These **CodeGraph tools** are defined in [`MemoryKnowledge/src/routes/tools.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/tools.ts) and registered under the `/v3/tools` API prefix, providing deterministic access to symbol metadata, call hierarchies, and file contents.

## Complete List of CodeGraph Tools

The tools are declared in the `CODE_GRAPH_TOOLS` array (lines 78‑95 in [`MemoryKnowledge/src/routes/tools.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/tools.ts)) and exposed via the `CODEGRAPH_QUERY_TOOL_NAMES` whitelist (lines 85‑87). Each tool performs a specific read‑only operation against the indexed graph.

### Metadata and Health Tools

- **`get_info`** – Returns basic metadata of the CodeGraph asset, including repository name, index status, and high‑level statistics. Requires no parameters.
- **`status`** – Performs a health check on the underlying index, returning counts of files, nodes, and edges. Requires no parameters.

### Search and Exploration Tools

- **`search`** – Executes a fast symbol‑name search that returns locations without source code. Ideal for quick look‑ups.
  - `query` (string, required): The symbol name to search.
  - `kind` (string, optional): Filter by kind (e.g., `function`, `class`).
  - `limit` (integer, default 10): Maximum results to return.

- **`explore`** – The preferred tool for most queries. Returns full source code grouped by file for a specific symbol, file path, or natural‑language question.
  - `query` (string, required): Symbol name, file path, or question.
  - `maxFiles` (integer, default 12): Maximum files to include in the response.

### Call Graph and Dependency Tools

- **`callers`** – Lists functions that invoke a given symbol.
  - `symbol` (string, required): Target symbol identifier.
  - `limit` (integer, default 20): Maximum callers to return.

- **`callees`** – Lists functions called by a given symbol.
  - `symbol` (string, required): Target symbol identifier.
  - `limit` (integer, default 20): Maximum callees to return.

- **`impact`** – Performs dependency traversal to show symbols affected by changing a given symbol.
  - `symbol` (string, required): Starting symbol for impact analysis.
  - `depth` (integer, default 2): Traversal depth for dependency graph.

### Detailed Inspection Tools

- **`node`** – Retrieves detailed information for a single symbol, optionally including its full source code.
  - `symbol` (string, required): Exact symbol identifier.
  - `includeCode` (boolean, default false): Whether to return source code.
  - `file` (string, optional): Restrict to specific file path.
  - `line` (integer, optional): Restrict to specific line number.

- **`files`** – Provides a navigable view of the indexed file hierarchy.
  - `path` (string, optional): Subdirectory to inspect.
  - `pattern` (string, optional): Glob pattern to filter files.
  - `format` (string, default `tree`): Display format (`tree`, `flat`, or `grouped`).

## Tool Registration and Implementation

According to the TencentDB-Agent-Memory source code, the tool registry is implemented in two layers:

1. **Definition Layer** – The `CODE_GRAPH_TOOLS` array in [`MemoryKnowledge/src/routes/tools.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/tools.ts) (lines 78‑95) contains the full schema definitions for all nine tools, including parameter types and descriptions.

2. **Exposition Layer** – The `CODEGRAPH_QUERY_TOOL_NAMES` export (lines 85‑87) defines the subset of tools available through the generic query endpoint, ensuring agents only discover supported operations.

The actual execution logic resides in [`MemoryKnowledge/src/engines/code/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/engines/code/index.ts), which bridges the HTTP API to the underlying `@colbymchenry/codegraph` package (version `^1.2.0` listed in [`MemoryKnowledge/package.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/package.json)).

## How to Use CodeGraph Tools

Agents interact with the tools through two primary HTTP endpoints under the `/v3/tools` namespace.

### Listing Available Tools

To discover which **CodeGraph tools** are registered for a specific knowledge asset:

```http
POST /v3/tools/list HTTP/1.1
Host: localhost:8125
Content-Type: application/json
x-tdai-service-id: my-service-id

{
  "knowledge_id": "codegraph_12345"
}

```

The response includes the tool name, description, and parameter schema:

```json
{
  "knowledge_id": "codegraph_12345",
  "type": "code-graph",
  "name": "my-repo",
  "status": "ready",
  "tools": [
    {
      "name": "explore",
      "description": "【首选工具】几乎任何问题都先用它…",
      "params": {
        "query": { "type": "string", "required": true },
        "maxFiles": { "type": "integer", "default": 12 }
      }
    }
  ]
}

```

### Invoking a Tool

To execute the `explore` tool and retrieve source code for a specific symbol:

```http
POST /v3/tools/call HTTP/1.1
Host: localhost:8125
Content-Type: application/json
x-tdai-service-id: my-service-id

{
  "knowledge_id": "codegraph_12345",
  "tool_name": "explore",
  "params": {
    "query": "AuthService loginUser",
    "maxFiles": 5
  }
}

```

The response groups results by file:

```json
{
  "ok": true,
  "data": {
    "files": [
      {
        "path": "src/auth/AuthService.ts",
        "content": "...full source of AuthService.loginUser..."
      }
    ]
  }
}

```

## Key Source Files

The following files define and implement the **CodeGraph tools** architecture:

- [`MemoryKnowledge/src/routes/tools.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/tools.ts) – Defines the `CODE_GRAPH_TOOLS` array and exports `CODEGRAPH_QUERY_TOOL_NAMES`.
- [`MemoryKnowledge/src/routes/code-graph.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/code-graph.ts) – Registers HTTP routes and binds the whitelisted tool names to the `/v3/tools/call` endpoint.
- [`MemoryKnowledge/src/engines/code/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/engines/code/index.ts) – Implements the execution bridge to the underlying `@colbymchenry/codegraph` engine.
- [`MemoryKnowledge/package.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/package.json) – Declares the `@colbymchenry/codegraph` dependency at version `^1.2.0`.

## Summary

- TencentDB Agent Memory provides nine read‑only **CodeGraph tools** via the `/v3/tools` HTTP namespace.
- Tools are defined in the `CODE_GRAPH_TOOLS` array and exposed through `CODEGRAPH_QUERY_TOOL_NAMES` in [`MemoryKnowledge/src/routes/tools.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/tools.ts).
- The `explore` tool is the recommended entry point for most symbol and source‑code queries.
- The `impact` tool performs dependency traversal to determine change effects up to a configurable depth.
- All tools require a valid `knowledge_id` and service authentication header (`x-tdai-service-id`).

## Frequently Asked Questions

### What is the difference between the `search` and `explore` CodeGraph tools?

The `search` tool performs a fast symbol‑name lookup that returns only location metadata (file path and line number) without source code, making it ideal for quick existence checks. The `explore` tool is the preferred general‑purpose interface that returns full source code grouped by file and accepts natural‑language queries in addition to exact symbol names.

### How do I verify that the CodeGraph index is ready for queries?

Invoke the `status` tool via the `/v3/tools/call` endpoint with an empty parameters object. This returns the current health of the index, including the number of indexed files, nodes, and edges. Alternatively, the `get_info` tool returns high‑level metadata including the repository name and processing state.

### Which parameters are required for analyzing the impact of a code change?

The `impact` tool requires the `symbol` parameter (string) to specify the starting node for dependency traversal. Optionally, you can provide the `depth` parameter (integer, default 2) to control how many levels of the call graph to traverse when calculating affected symbols.

### Where are the CodeGraph tool definitions located in the source code?

The tool schemas and metadata are defined in [`MemoryKnowledge/src/routes/tools.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/routes/tools.ts), specifically within the `CODE_GRAPH_TOOLS` array (lines 78‑95). The subset of tools exposed to the generic query endpoint is exported as `CODEGRAPH_QUERY_TOOL_NAMES` (lines 85‑87), while the runtime implementation resides in [`MemoryKnowledge/src/engines/code/index.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/engines/code/index.ts).