Code Knowledge Graph

niuma_code builds a structural knowledge graph from your codebase using its built-in LanguageParser. The graph indexes symbols, definitions, references, and dependencies — giving the LLM instant access to code structure without grep.

How It Works

On project open:
  LanguageParser parses source files
  → Extracts: classes, functions, imports, exports
  → Builds: symbol table + relationship graph
  → Stored in: .niuma/kg/

The knowledge graph is built on-demand — a three-factor decision avoids full re-parse on every startup:

Factor Condition
File changes detected New/modified/deleted files since last build
Time threshold More than 24 hours since last build
Manual trigger User explicitly requests rebuild

4 Retrieval Tools

locate_symbol

Find where a symbol is defined:

Tool: locate_symbol
Input: { "name": "UserService" }
Output: {
  "type": "class",
  "file": "app/services/user.py",
  "line": 42,
  "signature": "class UserService(BaseService):"
}

check_file_deps

List all files that import from / are imported by a given file:

Tool: check_file_deps
Input: { "path": "app/services/auth.py" }
Output: {
  "imports_from": ["app/models/user.py", "app/utils/crypto.py"],
  "imported_by": ["app/routes/auth.py", "tests/test_auth.py"]
}

find_references

Find all usages of a symbol across the codebase:

Tool: find_references
Input: { "name": "login" }
Output: [
  { "file": "app/services/auth.py", "line": 28, "context": "def login(email, password):" },
  { "file": "app/routes/auth.py", "line": 15, "context": "await auth_service.login(email, password)" },
  { "file": "tests/test_auth.py", "line": 42, "context": "result = auth_service.login(...)" }
]

trace_calls

Trace the call chain from a function:

Tool: trace_calls
Input: { "name": "handle_login", "depth": 3 }
Output: {
  "call_chain": [
    "handle_login → validate_email",
    "handle_login → auth_service.login → verify_password",
    "handle_login → auth_service.login → create_token"
  ]
}

Symbol Types Index

LanguageParser parses the following symbol types:

Symbol Languages Example
Class Python, JS/TS class UserService:
Function Python, JS/TS def get_user(id):
Method Python, JS/TS async def verify(token):
Variable Python BASE_URL = "..."
Import Python, JS/TS from app.models import User
Export JS/TS export default handler
Type TypeScript interface Config { ... }

Rebuild Decision

The knowledge graph rebuilds automatically based on three factors:

Should rebuild?
  → Has file changed since last build? → YES → Rebuild
  → Has >24h passed since last build?  → YES → Rebuild  
  → User ran /kg-rebuild?             → YES → Rebuild
  → Otherwise                          → NO  → Use cache

Cache location: .niuma/kg/ in project root (git-ignored by default).

Benefits Over grep

Aspect grep Knowledge Graph
Find definition Search by name (may match substrings) Exact symbol lookup by AST node
Find references Grep for string pattern Semantic reference tracking
Dependencies Manual analysis Automatic import graph
Call chain Manual tracing Automated call graph
Language support Pattern-based AST-based (language-aware)
Speed Scan all files O(1) lookup from index

Supported Languages

Full AST support via built-in LanguageParser:

Tips