# What Information Does the CodeGraph Index in TencentDB Agent Memory

> Discover what information CodeGraph indexes in TencentDB Agent Memory. Learn about static repository metadata and structural code graphs powering query tools.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: deep-dive
- Published: 2026-08-30

---

**The CodeGraph in TencentDB Agent Memory indexes two distinct layers of information: static repository metadata (including identifiers, repository URLs, visibility settings, and synchronization timestamps) persisted in the Knowledge store, and a structural code graph (containing file trees, symbol relationships, inverted search indexes, and call-graph utilities) generated by the CodeGraph engine to power eight query tools.**

The CodeGraph asset serves as a hybrid knowledge source within TencentDB Agent Memory that bridges administrative repository data with dynamic code analysis capabilities. According to the `TencentCloud/TencentDB-Agent-Memory` source code, this dual-layer architecture enables agents to perform semantic searches, impact analysis, and symbol exploration across indexed repositories while maintaining strict multi-tenant isolation.

## The Two-Layer Architecture of the CodeGraph Index

The indexed information is explicitly divided between persisted metadata and engine-generated structural content, as defined in [`MemoryKnowledge/src/store/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/types.ts) and the v3 API specification.

### Metadata Layer (Knowledge Store)

The first layer consists of administrative fields stored in the **Knowledge store** via the `IKnowledgeStore` contract. These fields control access, lifecycle, and discovery:

- **`code_graph_id`** – Unique identifier with the format `cg-` followed by an 8-digit suffix, defined in [`sdk/memory-core/typescript/src/v3/metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/metadata-types.ts) (lines 57-63).
- **`team_id`** and **`service_id`** – Ownership and tenant identifiers ensuring multi-tenant isolation.
- **Repository references** – `repo_name`, `repo_url`, `branch`, and optional `commit_hash` pointing to the source repository.
- **`visibility`** – Access control enum with values `private`, `team`, `restricted`, `agent`, or `task` (defined in [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts) line 14).
- **`status`** and **`internal_status`** – Lifecycle states (`pending`, `processing`, `ready`, `failed`) and engine-specific sub-states tracked in [`types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/types.ts) (lines 42-44).
- **`sync_error`** – Error messages from the latest synchronization attempt.
- **`stats_json`** – JSON blob containing file, node, and edge counts: `{ files, nodes, edges }`.
- **Timestamps** – `last_sync_at`, `created_at`, and `updated_at` for audit trailing.

### Structural Index Layer (Engine-Generated)

The second layer contains the actual code analysis generated by the CodeGraph engine during synchronization. According to [`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md) (lines 71-81), this includes:

- **File tree** – Complete list of source files accessible via the `/files` tool.
- **Symbol graph** – Nodes representing functions, classes, and variables, connected by edges representing call relationships.
- **Search index** – Token-level inverted index enabling full-text symbol search through the `/search` tool.
- **Explore index** – Per-file groupings of matched symbols with surrounding source code snippets for the `/explore` tool.
- **Call-graph utilities** – Directed relationship mappings supporting `/callers`, `/callees`, and `/impact` analysis.
- **Node detail** – Optional source snippets for individual symbols via the `/node` endpoint.
- **Status health check** – Index health verification through the `/status` tool.

## How the CodeGraph Index Is Created and Maintained

The indexing process follows a three-stage lifecycle defined in the v3 API documentation and implemented in [`MemoryKnowledge/src/store/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/types.ts).

**Creation.** Calling `POST /v3/code-graph/create` persists the metadata layer with `status` set to `pending` and immediately queues a background build job.

**Synchronization.** The `POST /v3/code-graph/sync` endpoint triggers the engine to scan the repository, generate the structural index, populate `stats_json` with file and node counts, and transition `status` to `ready`. If the engine crashes, the `markInterruptedAsFailed` routine (lines 38-40 in [`types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/types.ts)) automatically marks non-terminal assets as `failed`.

**Query Validation.** All eight query tools operate on id-only requests. Each tool first verifies that the caller's `service_id` matches the asset's `service_id` to enforce tenant isolation. If the asset status is not `ready`, tools return an empty result (`{ text: "", isError: false }`) rather than throwing an error.

## Query Tools Powered by the Indexed Data

Once the structural index layer is generated, agents can access the following tools defined in [`v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3-api-memoryknowledge-doc.md):

- **`/search`** – Token-level inverted index lookup for symbols.
- **`/explore`** – Retrieves matched symbols with surrounding source context.
- **`/files`** – Lists all indexed source files.
- **`/callers`** and **`/callees`** – Navigate the call graph upstream or downstream.
- **`/impact`** – Analyzes potential code impact from changes.
- **`/node`** – Fetches detailed source snippets for specific symbols.
- **`/status`** – Reports index health and readiness.

## SDK Examples for Interacting with the Index

The TypeScript SDK provides methods to create, sync, and query the CodeGraph index, as implemented in [`MemoryPanel/src/lib/api/knowledge-api.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/src/lib/api/knowledge-api.ts).

Create a new CodeGraph asset:

```typescript
import { MemoryClient } from '@tencentdb/agent-memory-sdk';
const client = new MemoryClient({ /* service config */ });

const result = await client.codeGraph.create({
  team_id: 't_123',
  repo_url: 'https://github.com/example/repo',
  branch: 'main',
  repo_name: 'repo',
});
// Returns: { code_graph_id: 'cg-1a2b3c4d', status: 'pending', ... }

```

Trigger a synchronization to build the structural index:

```typescript
await client.codeGraph.sync({ code_graph_id: 'cg-1a2b3c4d' });
// Returns: { code_graph_id: 'cg-1a2b3c4d', status: 'processing' }

```

Search the indexed symbol graph:

```typescript
const searchResult = await client.codeGraph.search({
  code_graph_id: 'cg-1a2b3c4d',
  query: 'UserLogin',
});
console.log(searchResult.data); 
// [{ symbol: 'login', file: 'src/auth.ts', line: 42 }, ...]

```

Explore symbols with source context:

```typescript
const exploreResult = await client.codeGraph.explore({
  code_graph_id: 'cg-1a2b3c4d',
  query: 'UserLogin',
  maxFiles: 5,
});
console.log(exploreResult.data.text); // Markdown-formatted snippets

```

Retrieve indexed metadata and statistics:

```typescript
const detail = await client.codeGraph.get({ code_graph_id: 'cg-1a2b3c4d' });
console.log(detail.data.stats); // { files: 120, nodes: 845, edges: 732 }

```

## Key Source Files Defining the Index Schema

The following files in the `TencentCloud/TencentDB-Agent-Memory` repository define the index structure and query contracts:

- **[`sdk/memory-core/typescript/src/v3/metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/sdk/memory-core/typescript/src/v3/metadata-types.ts)** – Defines `AssetType`, `KnowledgeEntity`, and the `visibility` enum for CodeGraph metadata.
- **[`MemoryKnowledge/src/store/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/types.ts)** – Implements the `IKnowledgeStore` contract and `CodeGraphRow` interface for persisted metadata.
- **[`MemoryKnowledge/v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/v3-api-memoryknowledge-doc.md)** – Documents the eight query tools and synchronization workflow.
- **[`MemoryPanel/src/lib/api/knowledge-api.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/src/lib/api/knowledge-api.ts)** – Client-side API wrappers used by the web UI for CodeGraph operations.
- **[`MemoryPanel/web/src/pages/CodePage/hooks/useCodeSources.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/CodePage/hooks/useCodeSources.ts)** – UI logic consuming the indexed data and status fields.

## Summary

- The **CodeGraph index** consists of two layers: persisted metadata (identifiers, repository info, timestamps) and engine-generated structural data (symbol graphs, search indexes).
- **Metadata** is stored in the Knowledge store via `IKnowledgeStore` and includes multi-tenant isolation fields (`service_id`, `team_id`) and lifecycle states (`pending`, `processing`, `ready`, `failed`).
- **Structural content** includes file trees, call graphs, inverted search indexes, and exploration data powering eight query tools (`/search`, `/explore`, `/callers`, `/callees`, `/impact`, `/files`, `/node`, `/status`).
- **Synchronization** is triggered via `POST /v3/code-graph/sync`, which populates `stats_json` with node and edge counts; failures are handled by `markInterruptedAsFailed`.
- **Tenant isolation** enforces that query tools verify matching `service_id` before returning structural index data.

## Frequently Asked Questions

### What is the difference between CodeGraph metadata and the structural index?

**Metadata** comprises administrative fields stored in the Knowledge store, including repository URLs, visibility settings, and synchronization timestamps defined in [`types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/types.ts) and [`metadata-types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/metadata-types.ts). The **structural index** is the engine-generated content produced during synchronization, containing the actual symbol graph, file tree, and search indexes referenced by the eight query tools.

### How does multi-tenant isolation work in CodeGraph queries?

Every query tool verifies that the caller's `service_id` matches the asset's `service_id` field before accessing the structural index, as specified in [`v3-api-memoryknowledge-doc.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/v3-api-memoryknowledge-doc.md). This ensures tenants cannot access CodeGraph assets belonging to other organizations, even if they possess the `code_graph_id`.

### What happens if a CodeGraph sync is interrupted?

If the CodeGraph engine crashes or is interrupted during synchronization, the `markInterruptedAsFailed` routine in [`MemoryKnowledge/src/store/types.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryKnowledge/src/store/types.ts) automatically transitions any non-terminal assets (those not already `ready` or `failed`) to the `failed` status, preventing agents from querying incomplete indexes.

### Which query tools are available after the CodeGraph index is ready?

Once `status` transitions to `ready`, agents can utilize all eight tools: `/files` for listing sources, `/search` for symbol lookup, `/explore` for contextual snippets, `/callers` and `/callees` for call graph navigation, `/impact` for change analysis, `/node` for detailed symbol inspection, and `/status` for health checks.