What Information Does the CodeGraph Index in TencentDB Agent Memory

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 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 (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 line 14).
• status and internal_status – Lifecycle states (pending, processing, ready, failed) and engine-specific sub-states tracked in 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 (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.

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) 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:

• /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.

Create a new CodeGraph asset:

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:

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

Search the indexed symbol graph:

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:

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:

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 – Defines AssetType, KnowledgeEntity, and the visibility enum for CodeGraph metadata.
• MemoryKnowledge/src/store/types.ts – Implements the IKnowledgeStore contract and CodeGraphRow interface for persisted metadata.
• MemoryKnowledge/v3-api-memoryknowledge-doc.md – Documents the eight query tools and synchronization workflow.
• 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 – 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 and 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. 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 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.

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