kin-retrieval

Reading a repository through the Kin graph

Kin parses a repository into entities, relationships, changes, and provenance, and answers questions from that graph. Where grep matches strings and a file read spends context on lines you did not need, these tools return the declaration, its neighborhood, and the graph state that produced the answer.

Reach for the graph first. Fall back to grep only for things the graph does not model: prose in comments, generated files, and text inside languages Kin does not parse.

Pick the tool by what you know

You know the name. Use semantic_search. It matches parsed declarations by name, kind, and language, so it returns functions, classes, structs, traits, enums, interfaces, types, and constants rather than every line that mentions the word. Each hit carries its file path, line range, signature, and a stable entity id. Despite the name it does not rank by vector similarity, so treat it as the fast exact-ish lookup.

You only know the behavior. Use semantic_locate. It ranks code against a natural-language query using the vector index, which is the retrieval that powers kin locate. Set granularity to entity for declarations or file for files. It needs the running daemon and an embedded graph, and it reports its coverage in the response.

You have an entity and need to understand it. Use get_context_pack. It bundles the target with its caller and import neighborhood into one prompt-sized payload, which replaces a chain of separate reads. get_entity_source returns just the implementation body when the pack is more than you need.

You need callers. Use find_references for everything that imports, calls, or references a symbol. Use graph_neighborhood when you want the dependency structure around an entity, with direction of out for what it depends on, in for what depends on it, and both for the merged view.

You need the path a value travels. Use trace_data_flow. It walks the call and data-flow chain from a focal entity and returns it as an ordered list of steps.