# CodeGraph for Codebase Understanding: Key Characteristics in TencentDB Agent Memory

> Discover the key characteristics of CodeGraph for codebase understanding. Learn how this metadata-only registry simplifies graph storage and processing for TencentDB Agent Memory.

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

---

**The CodeGraph is a metadata-only registry that captures structural relationships in codebases through a `code_graph_id`, delegating actual graph storage and processing to an external Knowledge Service while exposing lifecycle operations via HTTP APIs.**

In the TencentDB-Agent-Memory repository, CodeGraph serves as a specialized knowledge asset that enables AI agents to understand code structure without storing the actual graph data locally. This architecture separates metadata management in MemoryCore from compute-intensive graph operations handled by the Knowledge Service, creating a scalable solution for codebase intelligence.

## What Is CodeGraph?

CodeGraph functions as a **structured metadata asset** within the TencentDB Agent Memory ecosystem. Unlike traditional code analysis tools that embed graph data directly, this implementation treats the graph as an external service dependency.

According to the MemoryCore documentation, the system stores only identifiers, asset type classification (`code_graph`), status flags, and service endpoints within its metadata registry. The actual nodes, edges, and traversal data remain in the dedicated Knowledge Service, which exposes REST endpoints under `/v3/code-graph/*`.

This design allows the Memory system to maintain lightweight references while leveraging specialized infrastructure for complex graph computations.

## Key Characteristics of CodeGraph Assets

### Metadata-Only Architecture

The CodeGraph asset operates as a **pointer-based registry** rather than a content repository. Configuration parameters in [`MemoryCore/src/metadata/config/metadata_config_params.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/config/metadata_config_params.json) define the `code_graph.enabled` toggle, which controls whether agents can access graph capabilities at runtime.

This separation means MemoryCore records the existence and permissions of a CodeGraph without maintaining the underlying AST or dependency graph data, significantly reducing storage overhead in the control plane.

### Unique Identification System

Every CodeGraph receives a unique `code_graph_id` (UUID format) upon registration. As implemented in [`MemoryPanel/web/src/lib/knowledge-api.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/lib/knowledge-api.ts), this identifier serves as the mandatory address parameter for all subsequent operations, including synchronization, search queries, and deletion requests.

The immutable nature of this ID ensures consistent referencing across the distributed system, allowing the MemoryPanel UI and agent capabilities to reliably target specific graph instances.

### Lifecycle Management Operations

The [`knowledge-api.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/knowledge-api.ts) wrapper exposes five core HTTP POST operations that map to the Knowledge Service:

- **Register Meta** – Creates a new metadata entry linking a repository to the graph service
- **Sync** – Triggers re-indexing of the source repository to refresh graph structure
- **Search** – Executes keyword queries against indexed functions, classes, or symbols
- **Explore** – Performs graph-traversal queries to discover relationships between code entities
- **Delete** – Removes the metadata registration (does not delete source code)

These operations follow a stateless request pattern, with the MemoryProxy forwarding authenticated calls to the Knowledge Service endpoints.

### Capability Integration for Agents

Agents declare CodeGraph access through the capability system defined in [`MemoryProxy/src/tdai/capabilities.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/capabilities.ts). When `code_graph.enabled` is present in an agent’s capability manifest, the runtime grants permission to invoke graph queries during tool execution.

This capabilities-based model ensures that only authorized agents can consume graph insights, maintaining security boundaries while enabling sophisticated code reasoning workflows.

### Access Control and Security

CodeGraph assets inherit the **unified metadata ACL system** governing all knowledge assets in MemoryCore. Access permissions apply to the metadata record, meaning users, teams, or agents must possess appropriate rights to register, view, or delete graph references.

The permission model treats `code_graph` as a first-class asset type, ensuring consistent governance alongside documents, databases, and other knowledge sources.

## Working with the CodeGraph API

The TypeScript client in [`MemoryPanel/web/src/lib/knowledge-api.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/lib/knowledge-api.ts) provides typed methods for interacting with CodeGraph assets. Below are practical implementations for common workflows.

### Registering a New CodeGraph

To create a metadata entry for a repository, invoke the registration method with the team identifier:

```typescript
import { knowledgeApi } from '@/lib/knowledge-api';

// Initialize a CodeGraph for the specified team
await knowledgeApi.code.registerMeta(teamId, {
  repo_name: 'user-service',
  repo_url: 'https://github.com/example/user-service',
  description: 'Authentication microservice graph'
});

```

The Knowledge Service generates and returns the `code_graph_id` upon successful creation.

### Synchronizing Graph Data

Trigger re-indexing when the source repository changes to ensure structural accuracy:

```typescript
await knowledgeApi.code.sync(codeGraphId);

```

This operation forces the Knowledge Service to rebuild its internal graph representation from the latest commit state.

### Searching Code Elements

Query specific symbols or patterns within the indexed graph:

```typescript
const results = await knowledgeApi.code.search(codeGraphId, {
  query: 'UserService',
  kind: 'class',      // Filter: 'function', 'class', or 'any'
  limit: 20
});

```

Results include metadata about matched nodes without returning full graph topology.

### Exploring Relationships

Perform graph traversal to discover dependencies or callers:

```typescript
const relationships = await knowledgeApi.code.explore(codeGraphId, {
  query: 'UserController',
  depth: 2            // Optional traversal depth
});

```

This method returns connected nodes based on the graph structure maintained by the Knowledge Service.

### Deleting a CodeGraph

Remove the metadata registration when the asset is no longer needed:

```typescript
await knowledgeApi.code.delete([codeGraphId]);

```

This operation affects only the Knowledge Service reference; source code repositories remain untouched.

## Implementation Files and Source Code

The TencentDB-Agent-Memory repository distributes CodeGraph functionality across several key modules:

| File | Responsibility |
|------|--------------|
| [`MemoryCore/src/metadata/config/metadata_config_params.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/config/metadata_config_params.json) | Defines the `code_graph.enabled` feature flag and default configuration parameters |
| [`MemoryPanel/web/src/lib/knowledge-api.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/lib/knowledge-api.ts) | Client-side API wrapper exposing `registerMeta`, `sync`, `search`, `explore`, and `delete` methods |
| [`MemoryPanel/web/src/pages/code/CodePage/components/code-detail-view.tsx`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/code/CodePage/components/code-detail-view.tsx) | React component rendering the CodeGraph ID, binding status, and available actions |
| [`MemoryPanel/web/src/pages/code/CodePage/components/useCodeSources.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryPanel/web/src/pages/code/CodePage/components/useCodeSources.ts) | Custom hook managing CodeGraph loading, synchronization state, and agent binding logic |
| [`MemoryProxy/src/tdai/capabilities.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/capabilities.ts) | Declares the `code_graph` capability constant used in agent permission manifests |
| [`MemoryCore/README.md`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/README.md) | Documents the knowledge metadata model including CodeGraph asset specifications |

These components collectively demonstrate how the system bridges UI interactions, agent capabilities, and external graph services through a clean metadata abstraction layer.

## Summary

- **CodeGraph** acts as a lightweight metadata registry in TencentDB-Agent-Memory, storing only asset pointers while delegating graph computation to an external Knowledge Service.
- Each graph receives a unique `code_graph_id` defined in [`knowledge-api.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/knowledge-api.ts), serving as the canonical address for all lifecycle operations.
- Five core operations—**Register Meta**, **Sync**, **Search**, **Explore**, and **Delete**—enable full management of code intelligence assets via HTTP POST calls to `/v3/code-graph/*` endpoints.
- Agents access graph capabilities through the `code_graph` capability declared in [`MemoryProxy/src/tdai/capabilities.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryProxy/src/tdai/capabilities.ts), subject to metadata ACL permissions.
- The architecture maintains separation between the MemoryCore control plane and graph storage, optimizing for scalability and security in large codebases.

## Frequently Asked Questions

### How does CodeGraph store actual graph data without bloating the Memory system?

CodeGraph implements a **metadata-only storage pattern** where MemoryCore retains only the `code_graph_id`, service endpoint, and access permissions. The Knowledge Service maintains the actual graph nodes, edges, and indices externally. When agents request queries, the system forwards requests to the Knowledge Service rather than retrieving data from local storage, ensuring MemoryCore remains lightweight regardless of repository size.

### What is the difference between the Search and Explore operations in CodeGraph?

**Search** performs keyword-based lookups against indexed symbols (functions, classes, variables) similar to traditional code search, optionally filtered by entity type. **Explore** executes graph-traversal queries that follow relationships between nodes—such as call graphs or inheritance hierarchies—returning connected entities based on structural edges rather than text similarity. Use Search for finding symbols by name; use Explore for understanding architectural relationships.

### Can multiple agents share the same CodeGraph asset simultaneously?

Yes. The `code_graph_id` functions as a shared resource reference within the metadata ACL system. Multiple agents can declare the `code_graph` capability and query the same graph concurrently, provided they possess read permissions on the metadata asset. The Knowledge Service handles concurrent request processing, while MemoryCore manages access control and binding relationships through [`useCodeSources.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/useCodeSources.ts) logic in the Management console.

### Where is the `code_graph.enabled` configuration evaluated in the system?

The configuration flag resides in [`MemoryCore/src/metadata/config/metadata_config_params.json`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/metadata/config/metadata_config_params.json) and is evaluated at runtime to determine whether the CodeGraph feature appears in agent capability negotiations. This toggle can be scoped globally for the deployment or configured per-user, allowing administrators to gradually roll out graph-based code understanding features without restarting core services.