CodeGraph for Codebase Understanding: Key Characteristics in TencentDB Agent Memory

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 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, 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 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. 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 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:

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:

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:

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:

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:

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	Defines the code_graph.enabled feature flag and default configuration parameters
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	React component rendering the CodeGraph ID, binding status, and available actions
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	Declares the code_graph capability constant used in agent permission manifests
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, 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, 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 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 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.

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